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

package/dist/events-DDOsDu4X.d.ts

@@ -0,0 +1,2091 @@
+import { t as ComponentProps } from "./types-BbN28E3_.js";
+import * as React from "react";
+declare namespace reason_parts_d_exports {
+  export { auto, clearPress, closePress, dragSelection, escapeKey, focusOut, imperativeAction, inputChange, inputClear, itemKeyboardSelect, itemPress, keyboard, listNavigation, noResults, none, outsidePress, pointer, rangeSelection, siblingOpen, submenuTrigger, triggerContextMenu, triggerFocus, triggerHover, triggerPress };
+}
+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 rangeSelection: 'range-selection';
+declare const dragSelection: 'drag-selection';
+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';
+/** A suggestion menu's results settled empty with `noResults: 'close'`. */
+declare const noResults: 'no-results';
+declare const none: 'none';
+//#endregion
+//#region src/utils/events/create-event-details.d.ts
+/**
+ * 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 | TouchEvent;
+  [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>;
+}
+//#endregion
+//#region src/internal/popup-menu/components/checkbox-group/checkbox-group.d.ts
+interface PopupMenuCheckboxGroupState extends Record<string, unknown> {
+  /**
+   * Whether the checkbox 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 PopupMenuCheckboxGroupProps extends ComponentProps<'div', PopupMenuCheckboxGroup.State> {
+  /**
+   * The controlled array of checked item values.
+   */
+  value?: string[];
+  /**
+   * The default checked values for uncontrolled mode. @default []
+   */
+  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: CheckboxValueChangeEventDetails) => 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 checkbox items together and owns their checked state as one array of values.
+ * Renders a `<div>` element with role="group".
+ */
+declare const PopupMenuCheckboxGroup: React.ForwardRefExoticComponent<Omit<PopupMenuCheckboxGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuCheckboxGroup {
+  type State = PopupMenuCheckboxGroupState;
+  interface Props extends PopupMenuCheckboxGroupProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/checkbox-item/checkbox-item.d.ts
+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;
+  /** Whether a range or drag selection previews a different checked state for this item. */
+  pending: 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 when standalone; inside a checkbox group the
+ * group owns it (`checked`, `defaultChecked` and `onCheckedChange` are ignored).
+ * 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 {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/item/item.d.ts
+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 {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/link-item/link-item.d.ts
+interface PopupMenuLinkItemState extends Record<string, unknown> {
+  highlighted: boolean;
+  disabled: boolean;
+  first: boolean;
+  last: boolean;
+  firstInGroup: boolean;
+  lastInGroup: boolean;
+}
+interface PopupMenuLinkItemProps extends ComponentProps<'a', PopupMenuLinkItem.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 do not navigate and are skipped during keyboard navigation.
+   */
+  disabled?: boolean;
+  /** Callback when this item is selected (via click, Enter key, or shortcut). */
+  onSelect?: () => void;
+  /** Whether to force render this item regardless of filter results. @default false */
+  forceMount?: boolean;
+  /**
+   * Whether clicking this item should close the menu. Defaults to false because
+   * full-page navigation unmounts the menu anyway.
+   * @default false
+   */
+  closeOnClick?: boolean;
+  /** Keyboard shortcut to trigger this item. */
+  shortcut?: string;
+  /** Forces this row's relative order during score-based sorting. @default 0 */
+  forceOrder?: number;
+  /** Overrides this row's computed fuzzy-match score. */
+  forceScore?: number;
+}
+declare const PopupMenuLinkItem: React.ForwardRefExoticComponent<Omit<PopupMenuLinkItem.Props, "ref"> & React.RefAttributes<HTMLAnchorElement>>;
+declare namespace PopupMenuLinkItem {
+  type State = PopupMenuLinkItemState;
+  interface Props extends PopupMenuLinkItemProps {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/radio-group/radio-group.d.ts
+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 {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/radio-item/radio-item.d.ts
+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 {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/submenu-trigger/submenu-trigger.d.ts
+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 {}
+}
+//#endregion
+//#region src/internal/popup-menu/components/subpage-trigger/subpage-trigger.d.ts
+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 {}
+}
+//#endregion
+//#region src/internal/popup-menu/data-first/types.d.ts
+/**
+ * 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';
+  /**
+   * Milliseconds to wait after the search stops changing before passing it to
+   * the loader. While waiting, the loader counts as fetching, so the menu
+   * doesn't show "no results" or treat the search as finished too early.
+   * @default 0
+   */
+  debounce?: number;
+  /**
+   * 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;
+  };
+}
+type LinkItemRenderProps = {
+  id: string;
+  value: string;
+  href: string;
+} & Required<Pick<PopupMenuLinkItemProps, 'disabled'>> & Pick<PopupMenuLinkItemProps, 'closeOnClick' | 'onSelect' | 'shortcut' | 'forceOrder' | 'forceScore'>;
+interface LinkItemRenderParams {
+  node: PopupMenuNode;
+  props: LinkItemRenderProps;
+  context: RowRenderContext & {
+    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;
+  };
+}
+/**
+ * Props to spread onto the CheckboxGroup component.
+ * Derived from PopupMenuCheckboxGroupProps.
+ */
+type CheckboxGroupRenderProps = Required<Pick<PopupMenuCheckboxGroupProps, 'disabled'>> & Pick<PopupMenuCheckboxGroupProps, 'onValueChange'> & {
+  value: string[];
+};
+/**
+ * Parameters passed to checkbox group render functions.
+ */
+interface CheckboxGroupRenderParams {
+  /** The resolved menu node for this row — canonical identity (`node.id`), definition path, and tree links */
+  node: PopupMenuNode;
+  /** Props to spread onto the CheckboxGroup component */
+  props: CheckboxGroupRenderProps;
+  /** Context for conditional rendering */
+  context: GroupRenderContext & {
+    /** The checkbox group's label */
+    label?: string;
+    /** Current checked values */
+    value?: string[];
+    /** Whether the checkbox group is disabled */
+    disabled: boolean;
+  };
+  /** Pre-rendered checkbox items */
+  children: React.ReactNode;
+}
+/**
+ * Parameters passed to checkbox group label render functions.
+ */
+interface CheckboxGroupLabelRenderParams {
+  /** 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 checkbox group's label */
+    label?: string;
+    /** Current checked values */
+    value?: string[];
+    /** Whether the checkbox 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;
+}
+/**
+ * Link item node definition. Represents a menu row that navigates to `href` when activated.
+ */
+interface LinkItemDef extends BaseNodeDef, Required<Pick<PopupMenuLinkItemProps, 'value' | 'href'>>, Pick<PopupMenuLinkItemProps, 'keywords' | 'disabled' | 'onSelect' | 'closeOnClick' | 'shortcut' | 'forceOrder' | 'forceScore'> {
+  kind: 'link-item';
+  render: (params: LinkItemRenderParams) => 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;
+/**
+ * Checkbox group node definition.
+ * Represents a group of checkbox items whose checked state the group owns as one array of values.
+ * Props derived from PopupMenuCheckboxGroupProps.
+ */
+interface CheckboxGroupDef extends Pick<PopupMenuCheckboxGroupProps, 'onValueChange' | 'disabled'> {
+  kind: 'checkbox-group';
+  /** Unique identifier for this checkbox group */
+  id: string;
+  /** Optional group heading/label */
+  label?: string;
+  /** Whether the checkbox group is hidden */
+  hidden?: boolean;
+  /** Values of the currently checked items (controlled). */
+  value: string[];
+  /** Child nodes in this checkbox group - must be CheckboxItemDef nodes */
+  nodes: CheckboxItemDef[];
+  /** Optional render function for the checkbox group container */
+  render?: (params: CheckboxGroupRenderParams) => React.ReactNode;
+  /**
+   * Optional render function for the checkbox group's label row.
+   * Used by the default checkbox 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: CheckboxGroupLabelRenderParams) => React.ReactNode;
+}
+/**
+ * Helper function to create a checkbox group definition with proper typing.
+ */
+declare function defineCheckboxGroup(def: CheckboxGroupDef): CheckboxGroupDef;
+/**
+ * Union of all node definition types.
+ */
+type NodeDef = ItemDef | LinkItemDef | TreeItemDef | RadioItemDef | CheckboxItemDef | SubmenuDef | SubpageDef | SeparatorDef | GroupDef | RadioGroupDef | CheckboxGroupDef;
+/**
+ * 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;
+  /** The checkbox group this node belongs to, if any */
+  checkboxGroup: {
+    id: string;
+    label?: string;
+    checkboxGroupDef: CheckboxGroupDef;
+    menuNode: PopupMenuNode<CheckboxGroupDef>;
+  } | null;
+}
+type RowNodeDef = ItemDef | LinkItemDef | 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;
+  };
+  /** Checkbox group this node belongs to, if rendering inside one. Carries the def so the row can be wrapped in the group's value provider. */
+  checkboxGroup?: {
+    id: string;
+    label?: string;
+    def: CheckboxGroupDef;
+  };
+}
+/**
+ * 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 checkbox group node ready for display with its render context.
+ * Contains the checkbox group definition and its items.
+ */
+interface DisplayCheckboxGroupNode {
+  kind: 'checkbox-group';
+  node: PopupMenuNode<CheckboxGroupDef>;
+  context: GroupRenderContext;
+  items: DisplayRowNode[];
+  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 | DisplayCheckboxGroupNode | 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 DisplayCheckboxGroupNode.
+ */
+declare function isDisplayCheckboxGroupNode(node: DisplayNode): node is DisplayCheckboxGroupNode;
+/**
+ * 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 checkbox groups behave during deep search.
+ * - 'flatten': Checkbox group items are shown individually in the flat list (not recommended).
+ * - 'preserve': Checkbox group is shown with only matching items visible.
+ * - 'preserve-show-all': Checkbox group is shown with ALL items visible when any item matches.
+ *   This is useful when you want users to see all options in a checkbox group.
+ */
+type CheckboxGroupBehavior = 'flatten' | 'preserve' | 'preserve-show-all';
+/**
+ * How a surface's `asyncContent` rows combine with its `content`.
+ * See `DataSurfaceProps.asyncContentMode`.
+ */
+type AsyncContentMode = 'replace' | 'append';
+/**
+ * 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';
+/**
+ * How the descendants of a disabled branch (a submenu or subpage with
+ * `disabled: true`) participate in deep search.
+ * - 'exclude': descendants are not deep results; the disabled trigger still is.
+ *   Equivalent to the branch's `includeInDeepSearch` defaulting to `'trigger-only'`.
+ * - 'inherit': descendants are deep results that inherit `disabled` — shown, not selectable.
+ */
+type DisabledBranchBehavior = 'exclude' | 'inherit';
+/**
+ * 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;
+  /**
+   * How checkbox groups behave during search results.
+   * - 'flatten': Checkbox items shown individually (not recommended).
+   * - 'preserve': Only matching checkbox items are shown (default).
+   * - 'preserve-show-all': All checkbox items are shown when any item matches.
+   * @default 'preserve'
+   */
+  checkboxGroupSearchBehavior?: CheckboxGroupBehavior;
+  /**
+   * 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;
+  /**
+   * How descendants of a disabled branch appear in deep search results.
+   * - 'exclude': not shown; the disabled branch trigger still appears (default)
+   * - 'inherit': shown as deep results with inherited `disabled`
+   * An explicit `includeInDeepSearch` on the branch def always takes precedence.
+   * @default 'exclude'
+   */
+  disabledBranchBehavior?: DisabledBranchBehavior;
+}
+/**
+ * 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.
+   * How its rows combine with `content` is set by `asyncContentMode`.
+   */
+  asyncContent?: AsyncLoaderConfig;
+  /**
+   * How rows from `asyncContent` combine with `content` once they load.
+   * - `'replace'`: the loaded rows replace `content` (`content` shows until then).
+   * - `'append'`: `content` stays first and the loaded rows follow it. A loaded
+   *   row whose Definition Key matches a row already in `content` (including
+   *   rows inside groups and tree items) is dropped, so local rows win.
+   * @default 'replace'
+   */
+  asyncContentMode?: AsyncContentMode;
+  /**
+   * When rows from `asyncContent` appear.
+   * - `'stream'`: as soon as they load (local `content` shows meanwhile).
+   * - `'block'`: only once the loader has settled for the current search. Until
+   *   then the previous settled list stays up unchanged; before anything has
+   *   settled the list is empty and `Loading` shows. Rows kept from a previous
+   *   search while the next one loads don't count as settled.
+   *
+   * Deep search has its own `deepSearch.asyncResultBehavior`, which still shows
+   * the loading state while a new search loads.
+   * @default 'stream'
+   */
+  asyncContentReveal?: AsyncResultBehavior;
+  /** 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), radio groups (DisplayRadioGroupNode), or checkbox groups (DisplayCheckboxGroupNode)
+   * when groupSearchBehavior: 'preserve'.
+   */
+  nodes: DisplayNode[];
+  /**
+   * Function to render a node.
+   * Handles items, submenus, groups, radio groups, and checkbox 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;
+}
+//#endregion
+//#region src/internal/popup-menu/menu-tree/types.d.ts
+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, checkbox-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;
+//#endregion
+//#region src/internal/popup-menu/events.d.ts
+/**
+ * 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 | typeof rangeSelection | typeof dragSelection;
+/**
+ * Event details for checkbox item checked state changes.
+ */
+type CheckedChangeEventDetails = ChangeEventDetails<CheckedChangeReason>;
+/**
+ * Reasons why a checkbox group's value changed.
+ */
+type CheckboxValueChangeReason = typeof itemPress | typeof itemKeyboardSelect | typeof rangeSelection | typeof dragSelection;
+/**
+ * Event details for checkbox group value changes.
+ */
+type CheckboxValueChangeEventDetails = ChangeEventDetails<CheckboxValueChangeReason>;
+/**
+ * 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>;
+//#endregion
+export { LinkItemRenderParams as $, PopupMenuItemState as $t, CheckboxItemRenderProps as A, defineRadioGroup as At, DisplaySeparatorNode as B, PopupMenuSubmenuTriggerProps as Bt, CheckboxGroupBehavior as C, submenuTrigger as Cn, SubpageDef as Ct, CheckboxGroupRenderProps as D, triggerPress as Dn, TreeItemRenderParams as Dt, CheckboxGroupRenderParams as E, triggerHover as En, TreeItemDef as Et, DisplayCheckboxGroupNode as F, isDisplaySeparatorNode as Ft, GroupRenderContext as G, PopupMenuRadioGroup as Gt, GroupBehavior as H, PopupMenuRadioItem as Ht, DisplayGroupNode as I, PopupMenuSubpageTrigger as It, InitialQueryBehavior as J, PopupMenuLinkItem as Jt, GroupRenderParams as K, PopupMenuRadioGroupProps as Kt, DisplayNode as L, PopupMenuSubpageTriggerProps as Lt, DataSurfaceProps as M, isDisplayGroupNode as Mt, DeepSearchConfig as N, isDisplayRadioGroupNode as Nt, CheckboxItemDef as O, TreeItemRenderProps as Ot, DisabledBranchBehavior as P, isDisplayRowNode as Pt, LinkItemDef as Q, PopupMenuItemProps as Qt, DisplayRadioGroupNode as R, PopupMenuSubpageTriggerState as Rt, BreadcrumbNode as S, siblingOpen as Sn, SubpageContentRenderParams as St, CheckboxGroupLabelRenderParams as T, triggerFocus as Tn, SubpageTriggerRenderProps as Tt, GroupDef as U, PopupMenuRadioItemProps as Ut, DisplaySubpageNode as V, PopupMenuSubmenuTriggerState as Vt, GroupLabelRenderParams as W, PopupMenuRadioItemState as Wt, ItemRenderParams as X, PopupMenuLinkItemState as Xt, ItemDef as Y, PopupMenuLinkItemProps as Yt, ItemRenderProps as Z, PopupMenuItem as Zt, AsyncLoaderStatus as _, noResults as _n, StaticAsyncNodesConfig as _t, PopupMenuOpenChangeReason as a, PopupMenuCheckboxGroupState as an, RadioGroupBehavior as at, AsyncResultBehavior as b, pointer as bn, SubmenuRenderParams as bt, PopupMenuIdScope as c, closePress as cn, RadioGroupRenderParams as ct, AsyncContentMode as d, imperativeAction as dn, RadioItemRenderParams as dt, PopupMenuCheckboxItem as en, LinkItemRenderProps as et, AsyncLoaderConfig as f, inputChange as fn, RadioItemRenderProps as ft, AsyncLoaderSource as g, listNavigation as gn, SeparatorRenderParams as gt, AsyncLoaderResult as h, keyboard as hn, SeparatorDef as ht, PopupMenuOpenChangeEventDetails as i, PopupMenuCheckboxGroupProps as in, QueryLoaderConfig as it, DataListChildrenState as j, isDisplayCheckboxGroupNode as jt, CheckboxItemRenderParams as k, defineCheckboxGroup as kt, PopupMenuNode as l, escapeKey as ln, RadioGroupRenderProps as lt, AsyncLoaderLoadingPhase as m, itemPress as mn, ScoredNode as mt, HighlightChangeEventDetails as n, PopupMenuCheckboxItemState as nn, NodeDef as nt, RadioValueChangeEventDetails as o, ChangeEventDetails as on, RadioGroupDef as ot, AsyncLoaderFetchStatus as p, inputClear as pn, RowRenderContext as pt, IncludeInDeepSearch as q, PopupMenuRadioGroupState as qt, PopupMenuHighlightChangeHandler as r, PopupMenuCheckboxGroup as rn, QueryAsyncNodesConfig as rt, GetResolvedIdFn as s, GenericEventDetails as sn, RadioGroupLabelRenderParams as st, CheckboxValueChangeEventDetails as t, PopupMenuCheckboxItemProps as tn, LoaderComponentProps as tt, UnresolvedMenuNode as u, focusOut as un, RadioItemDef as ut, AsyncNodesConfig as v, none as vn, StaticLoaderConfig as vt, CheckboxGroupDef as w, triggerContextMenu as wn, SubpageTriggerRenderParams as wt, AsyncState as x, reason_parts_d_exports as xn, SubmenuRenderProps as xt, AsyncRenderState as y, outsidePress as yn, SubmenuDef as yt, DisplayRowNode as z, PopupMenuSubmenuTrigger as zt };
+//# sourceMappingURL=events-DDOsDu4X.d.ts.map