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

package/dist/ListboxStore-BtcTXpzi.d.cts

@@ -0,0 +1,351 @@
+import { ReactStore } from '@base-ui/utils/store';
+import { v as PopupMenuOpenChangeEventDetails, H as HighlightChangeEventDetails, P as PopupMenuOpenChangeReason } from './events-BPr8sRGH.cjs';
+
+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;
+}
+/**
+ * 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)
+ * - `append`: new items were appended to the end while preserving existing order
+ */
+type OrderedItemsUpdateReason = 'replace' | 'append';
+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 list/scroll container element */
+    listRef: React.RefObject<HTMLElement | null>;
+    /** Map of item ID to ref for the item's DOM element */
+    itemRefs: Map<string, React.RefObject<HTMLElement | null>>;
+}
+interface ListboxState {
+    /** Whether the listbox is open */
+    open: boolean;
+    /** Current search query */
+    search: string;
+    /** 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;
+}
+interface ListboxContext {
+    /** 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 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>;
+    /**
+     * 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;
+    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;
+    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, typeof selectors> {
+    constructor(initialState?: Partial<ListboxState>, context?: Partial<ListboxContext>);
+    /**
+     * 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;
+    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;
+    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;
+    /**
+     * 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;
+    /**
+     * 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;
+    registerGroup(id: string): () => void;
+    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;
+    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>): ListboxStore;
+}
+
+export { type DOMRefs as D, type FilterFn as F, type HighlightSource as H, type ItemRegistration as I, type ListboxContext as L, type SearchNormalizer as S, type VirtualItem as V, type ListboxState as a, ListboxStore as b };