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

package/dist/index-D8OrKThQ.d.ts

@@ -0,0 +1,977 @@
+import { a as PopupMenuOpenChangeReason, i as PopupMenuOpenChangeEventDetails, n as HighlightChangeEventDetails } from "./events-DDOsDu4X.js";
+import * as React$1 from "react";
+import { ReactStore } from "@base-ui/utils/store";
+//#region src/internal/listbox/contexts/group-context.d.ts
+interface GroupPositional {
+  first?: boolean;
+  last?: boolean;
+  firstInGroup?: boolean;
+  lastInGroup?: boolean;
+  firstGroup?: boolean;
+  lastGroup?: boolean;
+}
+interface GroupContextValue {
+  groupId?: string;
+  positional?: GroupPositional;
+}
+declare const GroupContext: React$1.Context<GroupContextValue | null>;
+declare function useGroupContext(): GroupContextValue | null;
+//#endregion
+//#region src/internal/listbox/contexts/item-context.d.ts
+interface ItemContextValue {
+  /** Unique ID for this item (for DOM id attribute) */
+  id: string;
+  /** Whether the item is highlighted */
+  highlighted: boolean;
+  /** Whether the item is disabled */
+  disabled: boolean;
+  /** Keyboard shortcut for this item */
+  shortcut?: string;
+}
+declare const ItemContext: React$1.Context<ItemContextValue | null>;
+declare function useItemContext(): ItemContextValue;
+declare function useMaybeItemContext(): ItemContextValue | null;
+//#endregion
+//#region src/utils/input-modality.d.ts
+/**
+ * How a popup/menu was opened. Mirrors Base UI's `openMethod`.
+ * `'keyboard'` covers any non-pointer activation.
+ */
+type OpenMethod = 'mouse' | 'touch' | 'pen' | 'keyboard';
+//#endregion
+//#region src/internal/listbox/store/ListboxStore.d.ts
+type FilterFn = (value: string, search: string, keywords?: string[]) => number;
+type SearchNormalizer = (search: string) => string;
+interface ItemRegistration {
+  value: string;
+  keywords?: string[];
+  groupId?: string;
+  disabled?: boolean;
+  /** Lower values are sorted earlier in score-based lists. */
+  forceOrder?: number;
+  /** Overrides computed fuzzy score in score-based lists. */
+  forceScore?: number;
+  /** Whether this item is a submenu trigger */
+  isSubmenuTrigger?: boolean;
+  /** Single character keyboard shortcut to trigger this item */
+  shortcut?: string;
+  /** Whether selecting this item should close the menu (default: true) */
+  closeOnClick?: boolean;
+  /** Whether this item can be activated via Enter/click (default: true). Non-activatable items remain highlightable. */
+  activatable?: boolean;
+}
+/** Kinds of rows that participate in positional attributes. */
+type ListboxRowKind = 'item' | 'group' | 'separator' | 'empty' | 'loading';
+/** A mounted row tracked for positional attributes, in DOM order. */
+interface ListboxOrderedRow {
+  /** Unique row id (stable per component instance). */
+  id: string;
+  kind: ListboxRowKind;
+  /** Set for option-like rows rendered inside a Group/RadioGroup. */
+  groupId?: string;
+}
+/**
+ * Pre-registered item for virtualization.
+ * This allows the store to know about all items even when they're not mounted.
+ * The `value` field serves as both the unique identifier and the filtering value.
+ */
+interface VirtualItem {
+  /** Value used as unique identifier and for filtering/matching */
+  value: string;
+  /** Additional keywords for filtering */
+  keywords?: string[];
+  /** Whether the item is disabled */
+  disabled?: boolean;
+}
+type HighlightSource = 'keyboard' | 'pointer' | 'auto' | null;
+/**
+ * Describes why the consumer updated ordered items when filter={false}.
+ * - `replace`: list was re-ordered/replaced (default); highlight moves to the first item
+ * - `append`: new items were appended to the end while preserving existing order
+ * - `refresh`: the list changed but the search did not (e.g. async results
+ *   arrived); keep the highlighted item while it is still present and enabled
+ */
+type OrderedItemsUpdateReason = 'replace' | 'append' | 'refresh';
+interface SetOrderedItemsOptions {
+  /** Why ordered items were updated. @default 'replace' */
+  reason?: OrderedItemsUpdateReason;
+}
+/**
+ * Refs for DOM elements used for scroll behavior.
+ * These are stored outside of reactive state to avoid unnecessary re-renders.
+ */
+interface DOMRefs {
+  /** Ref to the semantic listbox element */
+  listRef: React.RefObject<HTMLElement | null>;
+  /** Ref to the element that owns the list's scroll position */
+  listScrollContainerRef: React.RefObject<HTMLElement | null>;
+  /** Ref to the popup (visual container) element */
+  popupRef: React.RefObject<HTMLElement | null>;
+  /** Map of item ID to ref for the item's DOM element */
+  itemRefs: Map<string, React.RefObject<HTMLElement | null>>;
+  /** Map of group ID to ref for the group's DOM element */
+  groupRefs: Map<string, React.RefObject<HTMLElement | null>>;
+}
+interface ListboxState {
+  /** Whether the listbox is open internally when uncontrolled */
+  open: boolean;
+  /** Controlled open prop. When defined, selectors resolve this over `open`. */
+  openProp: boolean | undefined;
+  /**
+   * How the listbox was most recently opened (`mouse`/`touch`/`pen`/`keyboard`).
+   * `null` until first opened. Retained after close (only updated on open).
+   */
+  openMethod: OpenMethod | null;
+  /** Current internal search query when uncontrolled */
+  search: string;
+  /** Controlled search prop. When defined, selectors resolve this over `search`. */
+  searchProp: string | undefined;
+  /** Normalized search query used for filtering and visibility checks */
+  normalizedSearch: string;
+  /** Currently highlighted item ID */
+  highlightedId: string | null;
+  /** Source of the current highlight (keyboard or pointer) */
+  highlightSource: HighlightSource;
+  /** Whether an Input is present in the Surface */
+  hasInput: boolean;
+  /** Whether the input is currently active (rendered) when hideUntilActive mode is used */
+  inputActive: boolean;
+  /** Pending search character typed before input was active */
+  pendingSearch: string;
+  /** Filtered results: item ID to score */
+  filteredItems: Map<string, number>;
+  /** Groups that have at least one visible item */
+  visibleGroups: Set<string>;
+  /** Count of visible items */
+  filteredCount: number;
+  /** Counter to trigger re-filtering when items change */
+  filterTrigger: number;
+  /** Whether virtualization mode is enabled */
+  virtualized: boolean;
+  /** Count of virtual items (from items prop) */
+  virtualItemsCount: number;
+  /**
+   * Rows currently mounted in the DOM, sorted by document position.
+   * Mounted ⇔ visible, so this is the list of visible rows.
+   * Immutable: replaced wholesale on every registry change so selectors recompute.
+   */
+  orderedRows: readonly ListboxOrderedRow[];
+}
+interface ListboxContext$1 {
+  /** Filter function or false to disable filtering */
+  filter: FilterFn | false;
+  /** Function used to normalize search before filtering. */
+  normalizeSearch: SearchNormalizer;
+  /** Whether to loop navigation */
+  loop: boolean;
+  /**
+   * Controls auto-highlighting behavior when the menu opens.
+   * - `true`: highlight the first item (default)
+   * - `false`: don't auto-highlight any item
+   * - `string`: highlight the item with this specific value
+   */
+  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 (requires Surface to call clearSearch)
+   */
+  clearSearchOnClose: boolean | 'after-exit';
+  /** Whether to reset list scroll position when search changes. */
+  resetScrollOnSearch: boolean;
+  /** Whether hideUntilActive mode is enabled */
+  hideUntilActive: boolean;
+  /** ID for the list element (for aria-activedescendant) */
+  listId: string;
+  /** ID for the input element */
+  inputId: string;
+  /** Map of item ID to registration data */
+  readonly items: Map<string, ItemRegistration>;
+  /** Map of group ID to set of item IDs */
+  readonly groups: Map<string, Set<string>>;
+  /** Map of item ID to onSelect callback */
+  readonly itemSelects: Map<string, () => void>;
+  /** Map of submenu trigger ID to open callback */
+  readonly submenuOpens: Map<string, () => void>;
+  /** Map of submenu trigger ID to close callback */
+  readonly submenuCloses: Map<string, () => void>;
+  /** Map of shortcut key to item ID */
+  readonly shortcuts: Map<string, string>;
+  /** Map of row ID to its mounted DOM element (positional registry). */
+  readonly rowElements: Map<string, HTMLElement>;
+  /**
+   * Callback when open state changes.
+   * The second parameter contains event details including the reason for the change.
+   */
+  onOpenChange: (open: boolean, eventDetails: PopupMenuOpenChangeEventDetails) => void;
+  /** Callback when search state changes */
+  onSearchChange: ((search: string) => void) | undefined;
+  /**
+   * Pre-registered items for virtualization.
+   * When provided, navigation uses this array order instead of DOM registration order.
+   */
+  virtualItems: VirtualItem[];
+  /**
+   * Consumer-provided ordered list of item values when filter={false}.
+   * Used to determine correct navigation/highlight order when consumer handles filtering externally.
+   * Must always be provided when filter={false}.
+   */
+  orderedItems: string[];
+  /**
+   * Callback when highlighted item changes.
+   * Useful for synchronizing with virtualizers (scrollToIndex) and other UI state.
+   * The third parameter contains event details including the reason for the change.
+   */
+  onHighlightChange: ((id: string | null, index: number, eventDetails: HighlightChangeEventDetails) => void) | undefined;
+  /**
+   * DOM refs for scroll behavior.
+   * Stored in context (not state) to avoid re-renders.
+   */
+  refs: DOMRefs;
+  /**
+   * Callback when menu close animation completes.
+   * Used for resetting row width measurements.
+   */
+  onCloseComplete?: () => void;
+  /**
+   * Callback when popup close transition completes.
+   * Used by popup-layer features that should reset only after exit animations.
+   */
+  onPopupCloseComplete?: () => void;
+  /**
+   * Last known pointer position for detecting actual pointer movement.
+   * Used to prevent "phantom" highlights when content shifts under a stationary pointer.
+   */
+  lastPointerPosition: {
+    x: number;
+    y: number;
+  } | null;
+}
+declare const selectors: {
+  open: (state: ListboxState) => boolean;
+  openMethod: (state: ListboxState) => OpenMethod | null;
+  search: (state: ListboxState) => string;
+  normalizedSearch: (state: ListboxState) => string;
+  highlightedId: (state: ListboxState) => string | null;
+  highlightSource: (state: ListboxState) => HighlightSource;
+  hasInput: (state: ListboxState) => boolean;
+  inputActive: (state: ListboxState) => boolean;
+  pendingSearch: (state: ListboxState) => string;
+  filteredCount: (state: ListboxState) => number;
+  filteredItems: (state: ListboxState) => Map<string, number>;
+  visibleGroups: (state: ListboxState) => Set<string>;
+  virtualized: (state: ListboxState) => boolean;
+  isHighlighted: (state: ListboxState, itemId: string) => boolean;
+  isGroupVisible: (state: ListboxState, groupId: string) => boolean;
+  isFirstRow: (state: ListboxState, rowId: string) => boolean;
+  isLastRow: (state: ListboxState, rowId: string) => boolean;
+  isFirstGroup: (state: ListboxState, rowId: string) => boolean;
+  isLastGroup: (state: ListboxState, rowId: string) => boolean;
+  isFirstInGroup: (state: ListboxState, rowId: string) => boolean;
+  isLastInGroup: (state: ListboxState, rowId: string) => boolean;
+  getItemScore: (state: ListboxState, itemId: string) => number;
+  hasSearchWithNoResults: (state: ListboxState) => boolean;
+};
+/**
+ * Core store for listbox-like components.
+ * Handles item registration, filtering, navigation, and highlight state.
+ *
+ * Used by: DropdownMenu, ContextMenu, Select, CommandMenu
+ */
+declare class ListboxStore extends ReactStore<ListboxState, ListboxContext$1, typeof selectors> {
+  constructor(initialState?: Partial<ListboxState>, context?: Partial<ListboxContext$1>);
+  /**
+   * Set the open state with event details.
+   *
+   * @param open - The new open state
+   * @param reason - The reason for the state change (default: 'none')
+   * @param event - The native DOM event that triggered the change (optional)
+   */
+  setOpen(open: boolean, reason?: PopupMenuOpenChangeReason, event?: Event): void;
+  setSearch(search: string): void;
+  setSearchNormalizer(normalizeSearch: SearchNormalizer): void;
+  private syncNormalizedSearch;
+  private defaultSearchInitialized;
+  initializeDefaultSearch(defaultSearch: string): void;
+  setHighlightedId(id: string | null, cause?: HighlightSource): void;
+  /**
+   * Notify listeners about highlight changes.
+   * Called whenever highlightedId changes, regardless of virtualization or DOM state.
+   * Useful for virtualization scroll sync, analytics, or any other tracking needs.
+   *
+   * @param id - The newly highlighted item ID (or null if cleared)
+   * @param cause - What caused the highlight change
+   */
+  private notifyHighlightChange;
+  /**
+   * Scroll the highlighted item into view.
+   * Uses native scrollIntoView if the element is in the DOM.
+   * For virtualized lists, the onHighlightChange callback (called from setHighlightedId)
+   * should handle scrolling via the virtualizer.
+   *
+   * @param id - The item ID to scroll into view
+   */
+  private scrollItemIntoView;
+  /**
+   * Reveal the top of an item's group after the item has been scrolled into
+   * view. When keyboard navigation lands on the first visible item of a
+   * group, aligning the viewport to the item alone leaves the group's label
+   * clipped just above the viewport (e.g. when navigating upward or wrapping
+   * around). Scrolling up by the clipped amount aligns the viewport top with
+   * the group's top edge so the label is visible.
+   *
+   * No-ops when the item is not the first visible item of its group, when the
+   * group element is unknown or outside the list, or when the group's top is
+   * already visible (e.g. when navigating downward).
+   */
+  private maybeRevealGroupTop;
+  private scrollListToTop;
+  /** The element that scrolls the list: the first scrollable ancestor of the list element, or the list element itself. */
+  getScrollResetElement(listEl: HTMLElement): HTMLElement;
+  private isScrollableElement;
+  setHasInput(hasInput: boolean): void;
+  setInputActive(active: boolean): void;
+  setPendingSearch(search: string): void;
+  setHideUntilActive(enabled: boolean): void;
+  setVirtualized(virtualized: boolean): void;
+  setVirtualItems(items: VirtualItem[]): void;
+  /**
+   * Set the consumer-provided ordered items.
+   * Used when filter={false} and consumer controls item order/visibility.
+   * Must always be provided when filter={false}.
+   *
+   * @param items - Array of item IDs in display order
+   */
+  setOrderedItems(items: string[], options?: SetOrderedItemsOptions): void;
+  /**
+   * Highlights the first registered item in the ordered items (or clears the
+   * highlight when there is none). Uses the 'auto' source: not user-initiated,
+   * so submenus don't auto-open. No-op while closed.
+   */
+  highlightFirstOrderedItem(): void;
+  /**
+   * Try to auto-highlight when an item registers.
+   * This handles the case where orderedItems was set before items mounted.
+   * Only highlights if:
+   * - filter={false} (using orderedItems)
+   * - Menu is open
+   * - No item is currently highlighted
+   * - autoHighlightFirst is enabled
+   * - The registering item is the first in orderedItems
+   */
+  private maybeAutoHighlightOnRegister;
+  setOnHighlightChange(callback: ((id: string | null, index: number, eventDetails: HighlightChangeEventDetails) => void) | undefined): void;
+  /**
+   * Set the list element ref for scroll container detection.
+   */
+  setListRef(ref: React.RefObject<HTMLElement | null>): void;
+  /**
+   * Set the list scroll container ref for scroll position management.
+   * Use this when the semantic list element is rendered inside another
+   * scrollable container, such as a custom ScrollArea viewport.
+   */
+  setListScrollContainerRef(ref: React.RefObject<HTMLElement | null>): void;
+  /**
+   * Set the popup (visual container) ref. Used by popup-layer features such as
+   * Select's align-item-with-trigger positioning.
+   */
+  setPopupRef(ref: React.RefObject<HTMLElement | null>): void;
+  /**
+   * Register an item's DOM ref for scrollIntoView behavior.
+   * Returns a cleanup function.
+   */
+  registerItemRef(id: string, ref: React.RefObject<HTMLElement | null>): () => void;
+  /**
+   * Check if pointer has moved and should allow highlight.
+   * This prevents "phantom" highlights when content shifts under a stationary pointer
+   * (e.g., when search results change or menu items reorder).
+   *
+   * @param x - Current pointer X position
+   * @param y - Current pointer Y position
+   * @returns true if pointer has actually moved and highlight should be allowed
+   */
+  shouldAllowPointerHighlight(x: number, y: number): boolean;
+  /**
+   * Reset pointer position tracking.
+   * Call this when the menu opens or content changes significantly.
+   */
+  resetPointerPosition(): void;
+  /**
+   * Pre-register virtual items so they appear in filteredItems.
+   * This allows filtering to work for items that aren't mounted yet.
+   */
+  private preRegisterVirtualItems;
+  registerItem(id: string, registration: ItemRegistration): () => void;
+  /**
+   * Register a group. Optionally registers the group's DOM element ref,
+   * used for scroll positioning (e.g. revealing the group's label).
+   * Returns a cleanup function.
+   */
+  registerGroup(id: string, ref?: React.RefObject<HTMLElement | null>): () => void;
+  /**
+   * Register a mounted row element for positional tracking.
+   * Rows are kept in `state.orderedRows` sorted by DOM document position.
+   * Call from a layout effect once the element is mounted; the returned
+   * cleanup removes the row (call it when the element unmounts).
+   */
+  registerRow(id: string, element: HTMLElement, row: {
+    kind: ListboxRowKind;
+    groupId?: string;
+  }): () => void;
+  /**
+   * Compare two rows by DOM document position.
+   * Falls back to preserving current relative order when either element
+   * is missing or disconnected (Array.prototype.sort is stable).
+   */
+  private compareRowOrder;
+  registerItemSelect(id: string, onSelect: (() => void) | undefined): () => void;
+  registerSubmenuOpen(id: string, onOpen: (() => void) | undefined): () => void;
+  registerSubmenuClose(id: string, onClose: (() => void) | undefined): () => void;
+  /**
+   * Close all submenus except the one with the given ID.
+   * Used when hovering over a new submenu trigger to close sibling submenus.
+   */
+  closeSiblingSubmenus(exceptId: string | null): void;
+  highlightNext(): void;
+  highlightPrev(): void;
+  selectHighlighted(): void;
+  /**
+   * Select an item by its keyboard shortcut.
+   * Returns true if an item was found and selected, false otherwise.
+   */
+  selectByShortcut(key: string): boolean;
+  openSubmenuForHighlighted(): void;
+  isHighlightedSubmenuTrigger(): boolean;
+  /**
+   * Get the item registration for the highlighted item.
+   * Returns undefined if no item is highlighted.
+   */
+  getHighlightedItem(): ItemRegistration | undefined;
+  clearSearch(): void;
+  clearHighlight(): void;
+  highlightFirstItem(): void;
+  /**
+   * Apply auto-highlight based on the current context.autoHighlightFirst value.
+   * Called by Surface after updating the context to ensure correct value is used.
+   */
+  applyAutoHighlight(): void;
+  /**
+   * Highlight a specific item by its value.
+   * If the item is not visible or doesn't exist, falls back to highlighting the first item.
+   * Scrolls the highlighted item into view.
+   */
+  highlightItemByValue(value: string): void;
+  /**
+   * Returns whether filtering is disabled (consumer handles filtering externally).
+   */
+  isFilterDisabled(): boolean;
+  getVisibleItemIds(): string[];
+  /**
+   * Get the index of an item in the visible items list.
+   * Returns -1 if the item is not found or not visible.
+   */
+  getVisibleItemIndex(id: string): number;
+  /**
+   * Get the index of an item in the virtualItems array.
+   * This is used for virtualizer scrollToIndex which needs the raw array index,
+   * not the filtered/visible index.
+   * Returns -1 if not found or not in virtualized mode.
+   */
+  getVirtualItemIndex(value: string): number;
+  /**
+   * Validates and updates the highlighted item.
+   * This is the single source of truth for highlight management.
+   *
+   * @param options.forceFirst - Force highlight first item even if current is valid
+   * @param options.filteredItems - Use this map instead of state (for mid-update calls)
+   * @param options.newSearch - The search query for filteredItems (to detect search cleared)
+   */
+  private validateHighlight;
+  private recomputeFilteredItems;
+  static useStore(externalStore: ListboxStore | undefined, initialState?: Partial<ListboxState>, context?: Partial<ListboxContext$1>): ListboxStore;
+}
+//#endregion
+//#region src/internal/listbox/contexts/listbox-context.d.ts
+/**
+ * Virtualization configuration passed from Root/Submenu to Surface.
+ */
+interface VirtualizationConfig {
+  /** Whether virtualization mode is enabled */
+  virtualized: boolean;
+  /** Pre-registered items for virtualization */
+  items: VirtualItem[];
+  /**
+   * Callback when highlighted item changes (for scroll sync).
+   * The third parameter contains event details including the reason for the change.
+   */
+  onHighlightChange?: (id: string | null, index: number, eventDetails: HighlightChangeEventDetails) => void;
+}
+interface ListboxContextValue {
+  /** The Listbox store instance */
+  store: ListboxStore;
+  /** Nesting depth: 0 = root menu, 1+ = submenu */
+  depth: number;
+  /** Close the entire menu tree (deepest submenu to root, sequentially) */
+  closeAll: () => void;
+  /** Register a surface (submenu) for closeAll tracking. Returns unregister function. */
+  registerSurface: (depth: number, setOpen: (open: boolean) => void) => () => void;
+  /** Virtualization configuration (if enabled) */
+  virtualization?: VirtualizationConfig;
+}
+declare const ListboxContext: React$1.Context<ListboxContextValue | null>;
+declare function useListboxContext(): ListboxContextValue;
+declare function useMaybeListboxContext(): ListboxContextValue | null;
+//#endregion
+//#region src/internal/listbox/contexts/row-width-context.d.ts
+/**
+ * Context value for row width measurement.
+ * Provided by List when `measureRowWidth` is enabled.
+ */
+interface RowWidthContextValue {
+  /**
+   * Queue a row element for width measurement.
+   * Call this when a row mounts or becomes visible.
+   *
+   * @param element - The DOM element to measure
+   * @param id - Unique identifier for this row (used to avoid re-measuring)
+   */
+  queueMeasurement: (element: HTMLElement, id: string) => void;
+}
+/**
+ * Context for row width measurement.
+ * Items use this to self-register for measurement.
+ */
+declare const RowWidthContext: React$1.Context<RowWidthContextValue | null>;
+/**
+ * Hook to get the row width context.
+ * Throws an error if used outside of a List with `measureRowWidth` enabled.
+ */
+declare function useRowWidthContext(): RowWidthContextValue;
+/**
+ * Hook to optionally get the row width context.
+ * Returns null if not within a List with `measureRowWidth` enabled.
+ * This is the preferred hook for items that should work both with and without measurement.
+ */
+declare function useMaybeRowWidthContext(): RowWidthContextValue | null;
+//#endregion
+//#region src/internal/listbox/contexts/surface-context.d.ts
+interface SurfaceContextValue {
+  /** The Listbox store instance */
+  store: ListboxStore;
+  /** Unique identifier for this surface */
+  surfaceId: string;
+}
+declare const SurfaceContext: React$1.Context<SurfaceContextValue | null>;
+declare function useSurfaceContext(): SurfaceContextValue;
+declare function useMaybeSurfaceContext(): SurfaceContextValue | null;
+//#endregion
+//#region src/internal/listbox/hooks/use-listbox-item.d.ts
+/**
+ * Aim guard refs for submenu navigation.
+ * Optional - only needed for popup menus with submenus.
+ */
+interface AimGuardRefs {
+  /** Whether aim guard is currently active */
+  aimGuardActiveRef: React$1.RefObject<boolean>;
+  /** The depth at which aim guard is active (null when not guarding) */
+  guardedDepthRef: React$1.RefObject<number | null>;
+}
+/**
+ * Parameters for the useListboxItem hook.
+ */
+interface UseListboxItemParams {
+  /**
+   * Explicit unique identifier for this item in the store.
+   * Takes highest priority for item registration.
+   * Used by data-first APIs to ensure consistent IDs.
+   */
+  id?: string;
+  /**
+   * Unique value for this item used as identifier and for filtering.
+   * If not provided, will be inferred from textContent.
+   * Used for registration when `id` is not provided.
+   */
+  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 remain highlightable.
+   * @default true
+   */
+  activatable?: boolean;
+  /**
+   * Whether to force render this item regardless of filter results.
+   * @default false
+   */
+  forceMount?: 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.
+   * Useful for pinning or manually ranking rows in score-based views.
+   */
+  forceScore?: number;
+  /**
+   * Whether this item is a submenu trigger (for store registration).
+   * @default false
+   */
+  isSubmenuTrigger?: boolean;
+  /**
+   * Callback when this item is selected (via click or Enter key).
+   * For simple items, pass this directly. For checkbox/radio items,
+   * use registerSelect() to register a dynamic handler.
+   */
+  onSelect?: () => void;
+  /**
+   * Whether selecting this item should close the menu.
+   * @default true
+   */
+  closeOnClick?: boolean;
+  /**
+   * Callback invoked after selection occurs (via click).
+   * Called with the item's ID. The consumer handles any
+   * post-selection behavior like closing menus.
+   */
+  onAfterSelect?: (itemId: string) => void;
+  /**
+   * Children (used for text content inference when value is not provided).
+   */
+  children?: React$1.ReactNode;
+  /**
+   * Optional aim guard refs for popup menu navigation.
+   * When provided, pointer move events will respect the aim guard.
+   */
+  aimGuard?: AimGuardRefs;
+}
+/**
+ * Return value from the useListboxItem hook.
+ */
+interface UseListboxItemReturn {
+  /** Unique ID for this item (DOM ID for aria-activedescendant) */
+  id: string;
+  /**
+   * Store identifier for this item.
+   * Use this when calling store methods like setHighlightedId, registerSubmenuOpen, etc.
+   * This is the `value` prop (or inferred from textContent).
+   */
+  storeId: string;
+  /** Ref to attach to the item element */
+  ref: React$1.RefObject<HTMLDivElement | null>;
+  /** Callback ref that tracks the mounted row element for positional attributes. Merge into the rendered element's ref. */
+  rowRef: (element: HTMLElement | null) => void;
+  /** Positional state among visible rows (all false in virtualized mode). */
+  positional: {
+    first: boolean;
+    last: boolean;
+    firstInGroup: boolean;
+    lastInGroup: boolean;
+  };
+  /** Whether item is currently highlighted */
+  isHighlighted: boolean;
+  /** Whether item should be rendered (passes filter) */
+  isVisible: boolean;
+  /** Context value to provide to children via ItemContext.Provider */
+  contextValue: ItemContextValue;
+  /**
+   * Event handlers to spread on the element.
+   * These handle click, pointer move, and pointer down events.
+   */
+  handlers: {
+    onClick: React$1.MouseEventHandler<HTMLDivElement>;
+    onPointerMove: React$1.PointerEventHandler<HTMLDivElement>;
+    onPointerDown: React$1.PointerEventHandler<HTMLDivElement>;
+  };
+  /**
+   * Register a custom onSelect handler.
+   * This is useful for checkbox/radio items where the select behavior
+   * needs to be customized (e.g., toggle checked state).
+   * Returns an unregister function.
+   */
+  registerSelect: (handler: (() => void) | undefined) => () => void;
+}
+/**
+ * Hook that provides all shared logic for navigatable/highlightable listbox items.
+ *
+ * This hook handles:
+ * - Item registration with the listbox store
+ * - Highlight state management (keyboard and pointer)
+ * - Filter/search visibility
+ * - Scroll into view on keyboard navigation
+ * - Click, pointer move, and pointer down event handlers
+ * - Optional aim guard integration (for submenu navigation)
+ *
+ * @example
+ * ```tsx
+ * function CustomItem(props) {
+ *   const item = useListboxItem({
+ *     value: props.value,
+ *     disabled: props.disabled,
+ *     onSelect: props.onSelect,
+ *   })
+ *
+ *   if (!item.isVisible) return null
+ *
+ *   return (
+ *     <ItemContext.Provider value={item.contextValue}>
+ *       <div
+ *         ref={item.ref}
+ *         {...item.handlers}
+ *         data-highlighted={item.isHighlighted || undefined}
+ *       >
+ *         {props.children}
+ *       </div>
+ *     </ItemContext.Provider>
+ *   )
+ * }
+ * ```
+ */
+declare function useListboxItem(params: UseListboxItemParams): UseListboxItemReturn;
+//#endregion
+//#region src/internal/listbox/hooks/use-listbox-keyboard.d.ts
+/**
+ * Focus owner interface for keyboard handling.
+ * Optional - only needed for popup menus with multiple surfaces.
+ */
+interface FocusOwnerInterface {
+  /** Check if a surface is the current owner */
+  useState: (selector: 'isOwner', surfaceId: string) => boolean;
+  /** Set the owner surface ID */
+  setOwnerId: (id: string | null) => void;
+}
+/**
+ * Submenu context interface for keyboard handling.
+ * Optional - only needed for popup menus with submenus.
+ */
+interface SubmenuInterface {
+  /** Close this submenu */
+  setOpen: (open: boolean) => void;
+  /** Parent surface ID for focus transfer */
+  parentSurfaceId: string;
+  /** Whether Escape closes the root menu or just this submenu */
+  closeRootOnEsc?: boolean;
+}
+/**
+ * Subpage context interface for keyboard handling.
+ * Optional - only needed for popup menus with in-popup subpage navigation.
+ */
+interface SubpageInterface {
+  /** Pop one page from the current stack. */
+  goBack: () => boolean;
+  /** Parent surface ID for focus transfer after back navigation. */
+  parentSurfaceId: string | null;
+  /** Whether Escape closes the root menu instead of navigating back. */
+  closeRootOnEsc?: boolean;
+}
+interface UseListboxKeyboardParams {
+  /** The Listbox store instance */
+  store: ListboxStore;
+  /** Unique identifier for this surface */
+  surfaceId: string;
+  /** Whether keyboard handling is enabled */
+  enabled: boolean;
+  /** User's onKeyDown handler to compose with */
+  onKeyDown?: React$1.KeyboardEventHandler;
+  /**
+   * Callback when an item is selected via keyboard (Enter or shortcut).
+   * Called with selection details. The consumer handles any
+   * post-selection behavior like closing menus.
+   */
+  onSelect?: (details: {
+    itemId: string | null;
+    closeOnClick: boolean;
+  }) => void;
+  /**
+   * Callback to close the entire menu tree from the root.
+   * Used when Escape is pressed and closeRootOnEsc is true (default).
+   */
+  closeAll: () => void;
+  /** The FocusOwner store for managing focus ownership (optional) */
+  focusOwner?: FocusOwnerInterface;
+  /** Menu depth (0 for root, >0 for submenus) - defaults to 0 */
+  depth?: number;
+  /** Submenu context for ArrowLeft navigation back to parent (optional) */
+  submenuContext?: SubmenuInterface | null;
+  /** Subpage context for ArrowLeft/Ctrl+H navigation back (optional) */
+  subpageContext?: SubpageInterface | null;
+  /**
+   * Whether to enable type-to-search behavior.
+   * When true, printable characters will activate the input and set pending search.
+   * Used by List when hideUntilActive is enabled and input is not yet active.
+   * @default false
+   */
+  enableTypeToSearch?: boolean;
+  /**
+   * Whether to skip the focus owner check.
+   * When true, keyboard handling will work based on `enabled` prop alone,
+   * ignoring focus ownership. Useful for Combobox where the input is outside
+   * the Surface but should still handle keyboard navigation.
+   * @default false
+   */
+  skipFocusOwnerCheck?: boolean;
+}
+interface UseListboxKeyboardReturn {
+  /** Keyboard event handler to attach to the element */
+  handleKeyDown: React$1.KeyboardEventHandler;
+}
+/**
+ * Centralized keyboard navigation hook for listbox-like components.
+ * Handles arrow navigation, vim bindings, submenu open/close, and selection.
+ *
+ * This hook can be used standalone (for simple listboxes like Select/Command)
+ * or with focus owner and submenu support (for popup menus with nested menus).
+ */
+declare function useListboxKeyboard(params: UseListboxKeyboardParams): UseListboxKeyboardReturn;
+//#endregion
+//#region src/internal/listbox/hooks/use-sticky-row-width.d.ts
+interface UseStickyRowWidthOptions {
+  /**
+   * Ref to the list container element.
+   * Used to measure row widths and as a fallback target for the CSS variable.
+   */
+  listRef: React$1.RefObject<HTMLElement | null>;
+  /**
+   * Optional ref to the element where `--row-width` CSS variable should be applied.
+   * If not provided, uses the listRef element.
+   * Useful for applying the variable to a parent Popup element.
+   */
+  targetRef?: React$1.RefObject<HTMLElement | null>;
+  /**
+   * Optional maximum width cap in pixels.
+   * The measured width will never exceed this value.
+   */
+  maxWidth?: number;
+  /**
+   * Whether measurement is enabled.
+   * @default true
+   */
+  enabled?: boolean;
+}
+interface UseStickyRowWidthReturn {
+  /**
+   * Queue a row element for measurement.
+   * The element's natural width will be measured and tracked.
+   * Call this when a row mounts or becomes visible.
+   */
+  queueMeasurement: (element: HTMLElement, id: string) => void;
+  /**
+   * Reset all measurements.
+   * Call this when the menu closes to start fresh on next open.
+   */
+  resetMeasurements: () => void;
+  /**
+   * Clear the set of measured IDs without resetting the sticky max width.
+   * Call this when row content changes for the same IDs (e.g. browse rows
+   * re-render as breadcrumb rows when deep search toggles) so rows are
+   * re-measured. The width still only grows, never shrinks.
+   */
+  clearMeasuredIds: () => void;
+}
+/**
+ * Hook that measures row widths and maintains a sticky maximum width.
+ *
+ * This is useful for virtualized lists where the popup width should adapt
+ * to the content but never shrink as the user scrolls through items.
+ *
+ * The hook:
+ * 1. Measures each row's natural width (using `max-content`)
+ * 2. Tracks the maximum width seen across all rows
+ * 3. Applies `--row-width` CSS variable to the target element
+ * 4. Only grows the width, never shrinks (until reset)
+ *
+ * @example
+ * ```tsx
+ * const { queueMeasurement, resetMeasurements } = useStickyRowWidth({
+ *   listRef: myListRef,
+ *   maxWidth: 500,
+ * })
+ *
+ * // Queue items for measurement
+ * useLayoutEffect(() => {
+ *   if (itemRef.current) {
+ *     queueMeasurement(itemRef.current, itemId)
+ *   }
+ * }, [itemId])
+ *
+ * // Reset on menu close
+ * useEffect(() => {
+ *   if (!isOpen) {
+ *     resetMeasurements()
+ *   }
+ * }, [isOpen])
+ * ```
+ */
+declare function useStickyRowWidth(options: UseStickyRowWidthOptions): UseStickyRowWidthReturn;
+//#endregion
+//#region src/internal/listbox/utils/command-score.d.ts
+/**
+ * Fuzzy matching algorithm for command palette-style filtering.
+ * Vendored from cmdk (https://github.com/pacocoursey/cmdk)
+ *
+ * The scores are arranged so that a continuous match of characters will
+ * result in a total score of 1.
+ */
+/**
+ * Calculates a fuzzy match score between a string and an abbreviation.
+ *
+ * @param string - The string to match against
+ * @param abbreviation - The search query
+ * @param keywords - Optional additional keywords to include in matching
+ * @returns A score between 0 and 1, where 1 is a perfect match and 0 is no match
+ */
+declare function commandScore(string: string, abbreviation: string, keywords?: string[]): number;
+/**
+ * Default filter function for listbox items.
+ * Returns a score > 0 for matches, 0 for non-matches.
+ */
+declare const defaultFilter: typeof commandScore;
+//#endregion
+//#region src/internal/listbox/utils/normalize.d.ts
+/**
+ * Normalizes a value string for use in filtering and identification.
+ * Trims leading/trailing whitespace to match cmdk's behavior.
+ *
+ * @param value - The value to normalize
+ * @returns The trimmed value, or empty string if value is nullish
+ */
+declare function normalizeValue(value: string | undefined | null): string;
+/**
+ * Converts a value string to a URL-safe slug for use in IDs.
+ * - Trims whitespace
+ * - Converts to lowercase
+ * - Replaces spaces with hyphens
+ * - Removes non-alphanumeric characters (except hyphens)
+ * - Collapses multiple hyphens into one
+ * - Removes leading/trailing hyphens
+ *
+ * @example
+ * slugify("User Settings") // "user-settings"
+ * slugify("  Hello World!  ") // "hello-world"
+ * slugify("Café & Co.") // "caf-co"
+ *
+ * @param value - The value to slugify
+ * @returns The slugified value, or empty string if value is nullish
+ */
+declare function slugify(value: string | undefined | null): string;
+//#endregion
+export { useMaybeListboxContext as A, VirtualItem as B, RowWidthContextValue as C, ListboxContextValue as D, ListboxContext as E, ListboxContext$1 as F, GroupContext as G, ItemContextValue as H, ListboxState as I, useGroupContext as J, GroupContextValue as K, ListboxStore as L, FilterFn as M, HighlightSource as N, VirtualizationConfig as O, ItemRegistration as P, OrderedItemsUpdateReason as R, RowWidthContext as S, useRowWidthContext as T, useItemContext as U, ItemContext as V, useMaybeItemContext as W, useListboxItem as _, UseStickyRowWidthOptions as a, useMaybeSurfaceContext as b, FocusOwnerInterface as c, UseListboxKeyboardParams as d, UseListboxKeyboardReturn as f, UseListboxItemReturn as g, UseListboxItemParams as h, defaultFilter as i, DOMRefs as j, useListboxContext as k, SubmenuInterface as l, AimGuardRefs as m, slugify as n, UseStickyRowWidthReturn as o, useListboxKeyboard as p, GroupPositional as q, commandScore as r, useStickyRowWidth as s, normalizeValue as t, SubpageInterface as u, SurfaceContext as v, useMaybeRowWidthContext as w, useSurfaceContext as x, SurfaceContextValue as y, SearchNormalizer as z };
+//# sourceMappingURL=index-D8OrKThQ.d.ts.map