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

package/dist/type-guards-ybcHBB3C.d.ts

@@ -0,0 +1,350 @@
+import * as React from 'react';
+import { PopoverPositionerProps, Popover, PopoverRootProps } from '@base-ui/react/popover';
+import { U as UseListboxItemParams, f as UseListboxItemReturn, b as GroupPositional } from './use-listbox-item-NzZuY34-.js';
+import { C as ComponentProps } from './types-DT4FOOa2.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { B as PopupMenuItemState, A as PopupMenuItemProps, P as PopupMenuHighlightChangeHandler, aS as HighlightChangeEventDetails, N as NodeDef, aG as TreeItemDef } from './events-DOGItflK.js';
+import { V as VirtualItem } from './ListboxStore-BYBpGrOz.js';
+import { a as PopupMenuRootActions } from './scroll-arrow-CNd0tgME.js';
+
+interface SubmenuContextValue {
+    /** Whether the submenu is open */
+    open: boolean;
+    /** Set the submenu open state */
+    setOpen: (open: boolean) => void;
+    /**
+     * Latch set by explicit close actions (keyboard ArrowLeft/Ctrl+H/Escape-in-submenu,
+     * or clicking the open trigger). While set and the trigger remains highlighted,
+     * pointer/keyboard auto-open is suppressed. Reset when highlight leaves the trigger.
+     */
+    suppressAutoOpenRef: React.MutableRefObject<boolean>;
+    /** Reference to the trigger element */
+    triggerRef: React.RefObject<HTMLElement | null>;
+    /** Reference to the submenu content element (for aim guard rect calculations) */
+    contentRef: React.RefObject<HTMLElement | null>;
+    /** Surface ID of the parent menu (for keyboard navigation back) */
+    parentSurfaceId: string;
+    /** Surface ID of this submenu (for keyboard navigation into) */
+    childSurfaceId: string;
+    /**
+     * Whether pressing Escape in this submenu closes the entire menu from the root.
+     * When true, Escape closes the entire menu tree.
+     * When false, Escape only closes this submenu and moves focus to the parent.
+     * @default true
+     */
+    closeRootOnEsc: boolean;
+}
+declare function useSubmenuContext(): SubmenuContextValue;
+declare function useMaybeSubmenuContext(): SubmenuContextValue | null;
+
+interface SubpageContextValue {
+    /** Current page ID. */
+    pageId: string;
+    /** Surface ID for this page. */
+    surfaceId: string;
+    /** Surface ID for the previous page, if available. */
+    parentSurfaceId: string | null;
+    /** Whether this page is currently active. */
+    isActive: boolean;
+    /** Whether Escape should close the entire menu tree from this page. */
+    closeRootOnEsc: boolean;
+    /** Navigate back one page. Returns true when navigation happened. */
+    goBack: () => boolean;
+}
+declare function useSubpageContext(): SubpageContextValue;
+declare function useMaybeSubpageContext(): SubpageContextValue | null;
+
+interface SubpageRegistration {
+    pageId: string;
+    surfaceId: string;
+    closeRootOnEsc: boolean;
+}
+interface SubpageStackContextValue {
+    /** Active page ID; `null` when the root surface is active. */
+    activePageId: string | null;
+    /** Surface ID of the root surface. */
+    rootSurfaceId: string;
+    /** Surface ID for the currently active page. */
+    activeSurfaceId: string;
+    /** Whether there is a previous page to navigate back to. */
+    canGoBack: boolean;
+    /** Whether Escape in the active page should close the entire menu tree. */
+    shouldCloseRootOnEsc: boolean;
+    /** Open page IDs, bottom to top; empty at root. */
+    stack: readonly string[];
+    /** Register a page and return an unregister cleanup. */
+    registerPage: (registration: SubpageRegistration) => () => void;
+    /** Push a page onto the stack. Returns true when navigation happened. */
+    openPage: (pageId: string) => boolean;
+    /** Pop one page from the stack. Returns true when navigation happened. */
+    goBack: () => boolean;
+    /** Resolve a surface ID for a page ID. */
+    getSurfaceId: (pageId: string) => string | null;
+}
+declare const SubpageStackContext: React.Context<SubpageStackContextValue | null>;
+declare function useSubpageStack(): SubpageStackContextValue;
+declare function useMaybeSubpageStack(): SubpageStackContextValue | null;
+
+/**
+ * Extended align options for popup menus.
+ * - 'start' | 'center' | 'end': Standard Base UI alignment
+ * - 'list-start': Align trigger top with the top of the List component (horizontal sides only)
+ */
+type PopupMenuPositionerAlign = PopoverPositionerProps['align'] | 'list-start';
+interface PopupMenuPositionerProps extends Omit<PopoverPositionerProps, 'align' | 'style'> {
+    /**
+     * Override the virtual anchor from context.
+     * Useful for nested menus that need different positioning.
+     */
+    virtualAnchor?: {
+        getBoundingClientRect(): DOMRect;
+    };
+    /**
+     * How to align the popup relative to the specified side.
+     * - 'start': align to start of anchor
+     * - 'center': align to center of anchor
+     * - 'end': align to end of anchor
+     * - 'list-start': align the List component's top with the anchor top (horizontal sides only)
+     * @default 'start' for submenus, 'center' for root dropdowns
+     */
+    align?: PopupMenuPositionerAlign;
+    /**
+     * Custom styles for the positioner.
+     * Note: During list-start alignment measurement, `transition: 'none'` is
+     * temporarily applied to prevent visual flash.
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * Positions the popup menu against its anchor.
+ * Wraps Popover.Positioner with:
+ * - Automatic virtualAnchor from PopupMenuContext (for context menus)
+ * - Smart default positioning based on depth and menu type
+ * - Smart collision avoidance: shift for horizontal menus, flip for vertical
+ * - 'list-start' alignment for horizontal submenus
+ *
+ * Renders a `<div>` element.
+ */
+declare const PopupMenuPositioner: React.ForwardRefExoticComponent<Omit<PopupMenuPositionerProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuPositioner {
+    type Props = PopupMenuPositionerProps;
+    type State = Popover.Positioner.State;
+}
+
+interface UsePopupMenuItemParams extends Omit<UseListboxItemParams, 'aimGuard' | 'onAfterSelect'> {
+    /**
+     * Whether clicking this item should close the menu.
+     * @default true
+     */
+    closeOnClick?: boolean;
+}
+interface UsePopupMenuItemReturn extends UseListboxItemReturn {
+    /** Whether this item is effectively disabled (item disabled OR menu disabled). */
+    disabled: boolean;
+}
+/**
+ * Hook that provides all shared logic for navigatable/highlightable popup menu items.
+ * This is a thin wrapper around useListboxItem that automatically adds aim-guard
+ * support and handles close-on-click behavior.
+ *
+ * @see useListboxItem for full documentation
+ */
+declare function usePopupMenuItem(params: UsePopupMenuItemParams): UsePopupMenuItemReturn;
+
+interface PopupMenuRadioItemIndicatorState extends Record<string, unknown> {
+    /**
+     * Whether the parent radio item is currently selected/checked.
+     */
+    checked: boolean;
+    /**
+     * Whether the parent radio item is currently highlighted.
+     */
+    highlighted: boolean;
+    /**
+     * Whether the parent radio item is disabled.
+     */
+    disabled: boolean;
+}
+interface PopupMenuRadioItemIndicatorProps extends ComponentProps<'span', PopupMenuRadioItemIndicator.State> {
+    /**
+     * Whether to keep the indicator mounted in the DOM when unchecked.
+     * Useful for animations.
+     * @default false
+     */
+    keepMounted?: boolean;
+}
+/**
+ * A visual indicator that shows when a RadioItem is selected.
+ * Must be used within a RadioItem component.
+ * Renders a `<span>` element with aria-hidden="true".
+ */
+declare const PopupMenuRadioItemIndicator: React.ForwardRefExoticComponent<Omit<PopupMenuRadioItemIndicator.Props, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare namespace PopupMenuRadioItemIndicator {
+    type State = PopupMenuRadioItemIndicatorState;
+    interface Props extends PopupMenuRadioItemIndicatorProps {
+    }
+}
+
+interface PopupMenuGroupValueProps {
+    /** Group id items register under. Omit for ungrouped rows that only need positional flags. */
+    groupId?: string;
+    /** Positional flags for this row; each defined flag overrides the store-derived value. */
+    positional?: GroupPositional;
+    children: React.ReactNode;
+}
+/**
+ * Headless provider for group membership and positional state.
+ * Renders no DOM. Use to wrap individual rows in virtualized lists where
+ * the store cannot derive position from mounted order.
+ */
+declare function PopupMenuGroupValue(props: PopupMenuGroupValueProps): react_jsx_runtime.JSX.Element;
+declare namespace PopupMenuGroupValue {
+    interface Props extends PopupMenuGroupValueProps {
+    }
+}
+
+interface PopupMenuTreeState extends Record<string, unknown> {
+    depth: number;
+}
+interface PopupMenuTreeProps extends ComponentProps<'div', PopupMenuTree.State> {
+    children: React.ReactNode;
+}
+declare const PopupMenuTree: React.ForwardRefExoticComponent<Omit<PopupMenuTree.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuTree {
+    type State = PopupMenuTreeState;
+    interface Props extends PopupMenuTreeProps {
+    }
+}
+
+interface PopupMenuTreeConnectorState extends Record<string, unknown> {
+    depth: number;
+}
+interface PopupMenuTreeConnectorProps extends ComponentProps<'span', PopupMenuTreeConnector.State> {
+    depth?: number;
+}
+declare const PopupMenuTreeConnector: React.ForwardRefExoticComponent<Omit<PopupMenuTreeConnector.Props, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare namespace PopupMenuTreeConnector {
+    type State = PopupMenuTreeConnectorState;
+    interface Props extends PopupMenuTreeConnectorProps {
+    }
+}
+
+interface PopupMenuTreeItemProps extends Omit<PopupMenuItemProps, 'activatable'> {
+    /** Whether this tree item can be activated. @default true */
+    selectable?: boolean;
+    /** Explicit tree depth override. */
+    depth?: number;
+}
+declare const PopupMenuTreeItem: React.ForwardRefExoticComponent<Omit<PopupMenuTreeItem.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace PopupMenuTreeItem {
+    type State = PopupMenuItemState;
+    interface Props extends PopupMenuTreeItemProps {
+    }
+}
+
+interface PopupMenuSubmenuRootProps extends Omit<PopoverRootProps, 'open' | 'onOpenChange' | 'defaultOpen' | 'actionsRef'> {
+    /**
+     * Whether the submenu is open.
+     * Use for controlled mode.
+     */
+    open?: boolean;
+    /**
+     * Callback when the open state changes.
+     * The second parameter contains event details including the reason for the change.
+     */
+    onOpenChange?: (open: boolean, eventDetails: Popover.Root.ChangeEventDetails) => void;
+    /**
+     * Whether the submenu is initially open.
+     * Use for uncontrolled mode.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Whether pressing Escape in this submenu closes the entire menu from the root.
+     * When true (default), Escape closes the entire menu tree.
+     * When false, Escape only closes this submenu and moves focus to the parent.
+     * @default true
+     */
+    closeRootOnEsc?: boolean;
+    /**
+     * Whether virtualization mode is enabled for this submenu.
+     * When true, items should provide an explicit `index` prop and
+     * the `items` prop should be provided for navigation to work correctly.
+     * @default false
+     */
+    virtualized?: boolean;
+    /**
+     * Pre-registered items for virtualization.
+     * When provided with `virtualized={true}`, this allows navigation to work
+     * for items that aren't currently mounted in the DOM.
+     */
+    items?: VirtualItem[];
+    /**
+     * Callback when the highlighted item changes. `id` is first; `node` is the
+     * resolved menu node enrichment and may be null.
+     * Useful for synchronizing with a virtualizer (e.g., scrollToIndex).
+     */
+    onHighlightChange?: PopupMenuHighlightChangeHandler<HighlightChangeEventDetails>;
+    /**
+     * Event handler called after any open/close animations have completed.
+     * When `clearSearchOnClose="after-exit"` is set on Surface, the search
+     * will be cleared before this callback is invoked.
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
+    /**
+     * Whether this submenu should ignore user interaction.
+     * Also inherits disabled state from its parent menu.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * A ref to imperative actions.
+     * - `close`: closes the submenu imperatively.
+     * - `unmount`: unmounts the popup imperatively (when keep-mounted mode is enabled).
+     * - `setDisabled`: enables/disables the submenu imperatively.
+     */
+    actionsRef?: React.RefObject<PopupMenuSubmenuRoot.Actions | null>;
+    children: React.ReactNode;
+}
+/**
+ * Groups all parts of a submenu.
+ * Manages open state and provides context to children.
+ * Creates its own ListboxStore independent from the parent menu.
+ * Doesn't render its own HTML element.
+ */
+declare function PopupMenuSubmenuRoot(props: PopupMenuSubmenuRootProps): react_jsx_runtime.JSX.Element;
+declare namespace PopupMenuSubmenuRoot {
+    interface Props extends PopupMenuSubmenuRootProps {
+    }
+    type ChangeEventDetails = Popover.Root.ChangeEventDetails;
+    type Actions = PopupMenuRootActions;
+}
+
+interface PopupMenuSubmenuTriggerIndicatorState extends Record<string, unknown> {
+    /**
+     * Whether the submenu popup is open.
+     */
+    popupOpen: boolean;
+    /**
+     * Whether the submenu owns keyboard focus.
+     */
+    popupFocused: boolean;
+}
+interface PopupMenuSubmenuTriggerIndicatorProps extends ComponentProps<'span', PopupMenuSubmenuTriggerIndicator.State> {
+}
+/**
+ * An indicator element for submenu triggers that reflects the submenu's open and focus state.
+ * Typically used to render a chevron or arrow icon.
+ * Must be used within PopupMenu.SubmenuTrigger.
+ * Renders a `<span>` element.
+ */
+declare const PopupMenuSubmenuTriggerIndicator: React.ForwardRefExoticComponent<Omit<PopupMenuSubmenuTriggerIndicator.Props, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare namespace PopupMenuSubmenuTriggerIndicator {
+    type State = PopupMenuSubmenuTriggerIndicatorState;
+    interface Props extends PopupMenuSubmenuTriggerIndicatorProps {
+    }
+}
+
+declare function isTreeItemDef(node: NodeDef): node is TreeItemDef;
+
+export { PopupMenuGroupValue as P, type SubmenuContextValue as S, type UsePopupMenuItemParams as U, PopupMenuPositioner as a, PopupMenuRadioItemIndicator as b, PopupMenuSubmenuRoot as c, PopupMenuSubmenuTriggerIndicator as d, PopupMenuTree as e, PopupMenuTreeConnector as f, PopupMenuTreeItem as g, type PopupMenuPositionerAlign as h, type PopupMenuPositionerProps as i, type PopupMenuRadioItemIndicatorProps as j, type PopupMenuRadioItemIndicatorState as k, type PopupMenuSubmenuRootProps as l, type PopupMenuSubmenuTriggerIndicatorProps as m, type PopupMenuSubmenuTriggerIndicatorState as n, type SubpageContextValue as o, type SubpageStackContextValue as p, useMaybeSubpageContext as q, useMaybeSubpageStack as r, useSubmenuContext as s, useSubpageContext as t, useMaybeSubmenuContext as u, useSubpageStack as v, type UsePopupMenuItemReturn as w, usePopupMenuItem as x, isTreeItemDef as y, SubpageStackContext as z };

package/dist/types-DT4FOOa2.d.cts

@@ -0,0 +1,51 @@
+import * as React from 'react';
+
+/**
+ * Render function that receives props and state, returns a React element.
+ */
+type ComponentRenderFn<Props, State> = (props: Props, state: State) => React.ReactElement<unknown>;
+/**
+ * HTML props with ref support.
+ */
+type HTMLProps<T = any> = React.HTMLAttributes<T> & {
+    ref?: React.Ref<T> | undefined;
+};
+/**
+ * React synthetic event augmented by Base UI's mergeProps utility.
+ */
+type PreventableBaseHandlerEvent<E extends React.SyntheticEvent<Element, Event>> = E & {
+    preventBaseUIHandler: () => void;
+    readonly baseUIHandlerPrevented?: boolean;
+};
+type WithPreventableBaseHandler<T> = T extends (event: infer E) => infer R ? E extends React.SyntheticEvent<Element, Event> ? (event: PreventableBaseHandlerEvent<E>) => R : T : T;
+/**
+ * Adds Base UI's preventBaseUIHandler event typing to React event handlers.
+ */
+type WithPreventableBaseHandlers<T> = {
+    [K in keyof T]: WithPreventableBaseHandler<T[K]>;
+};
+/**
+ * Props shared by all Bazza UI components.
+ * Includes className (string or state-based function), render prop, and style (object or state-based function).
+ */
+type ComponentProps<ElementType extends React.ElementType, State, RenderFunctionProps = HTMLProps> = Omit<React.ComponentPropsWithRef<ElementType>, 'className' | 'color' | 'defaultValue' | 'defaultChecked'> & {
+    /**
+     * CSS class applied to the element, or a function that
+     * returns a class based on the component's state.
+     */
+    className?: string | ((state: State) => string | undefined);
+    /**
+     * Allows you to replace the component's HTML element
+     * with a different tag, or compose it with another component.
+     *
+     * Accepts a `ReactElement` or a function that returns the element to render.
+     */
+    render?: ComponentRenderFn<RenderFunctionProps, State> | React.ReactElement;
+    /**
+     * Style applied to the element, or a function that
+     * returns a style object based on the component's state.
+     */
+    style?: React.CSSProperties | ((state: State) => React.CSSProperties | undefined);
+};
+
+export type { ComponentProps as C, WithPreventableBaseHandlers as W, ComponentRenderFn as a };

package/dist/types-DT4FOOa2.d.ts

@@ -0,0 +1,51 @@
+import * as React from 'react';
+
+/**
+ * Render function that receives props and state, returns a React element.
+ */
+type ComponentRenderFn<Props, State> = (props: Props, state: State) => React.ReactElement<unknown>;
+/**
+ * HTML props with ref support.
+ */
+type HTMLProps<T = any> = React.HTMLAttributes<T> & {
+    ref?: React.Ref<T> | undefined;
+};
+/**
+ * React synthetic event augmented by Base UI's mergeProps utility.
+ */
+type PreventableBaseHandlerEvent<E extends React.SyntheticEvent<Element, Event>> = E & {
+    preventBaseUIHandler: () => void;
+    readonly baseUIHandlerPrevented?: boolean;
+};
+type WithPreventableBaseHandler<T> = T extends (event: infer E) => infer R ? E extends React.SyntheticEvent<Element, Event> ? (event: PreventableBaseHandlerEvent<E>) => R : T : T;
+/**
+ * Adds Base UI's preventBaseUIHandler event typing to React event handlers.
+ */
+type WithPreventableBaseHandlers<T> = {
+    [K in keyof T]: WithPreventableBaseHandler<T[K]>;
+};
+/**
+ * Props shared by all Bazza UI components.
+ * Includes className (string or state-based function), render prop, and style (object or state-based function).
+ */
+type ComponentProps<ElementType extends React.ElementType, State, RenderFunctionProps = HTMLProps> = Omit<React.ComponentPropsWithRef<ElementType>, 'className' | 'color' | 'defaultValue' | 'defaultChecked'> & {
+    /**
+     * CSS class applied to the element, or a function that
+     * returns a class based on the component's state.
+     */
+    className?: string | ((state: State) => string | undefined);
+    /**
+     * Allows you to replace the component's HTML element
+     * with a different tag, or compose it with another component.
+     *
+     * Accepts a `ReactElement` or a function that returns the element to render.
+     */
+    render?: ComponentRenderFn<RenderFunctionProps, State> | React.ReactElement;
+    /**
+     * Style applied to the element, or a function that
+     * returns a style object based on the component's state.
+     */
+    style?: React.CSSProperties | ((state: State) => React.CSSProperties | undefined);
+};
+
+export type { ComponentProps as C, WithPreventableBaseHandlers as W, ComponentRenderFn as a };

package/dist/use-listbox-item-NzZuY34-.d.cts

@@ -0,0 +1,212 @@
+import * as React from 'react';
+
+interface GroupPositional {
+    first?: boolean;
+    last?: boolean;
+    firstInGroup?: boolean;
+    lastInGroup?: boolean;
+    firstGroup?: boolean;
+    lastGroup?: boolean;
+}
+interface GroupContextValue {
+    groupId?: string;
+    positional?: GroupPositional;
+}
+declare const GroupContext: React.Context<GroupContextValue | null>;
+declare function useGroupContext(): GroupContextValue | null;
+
+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.Context<ItemContextValue | null>;
+declare function useItemContext(): ItemContextValue;
+declare function useMaybeItemContext(): ItemContextValue | null;
+
+/**
+ * Aim guard refs for submenu navigation.
+ * Optional - only needed for popup menus with submenus.
+ */
+interface AimGuardRefs {
+    /** Whether aim guard is currently active */
+    aimGuardActiveRef: React.RefObject<boolean>;
+    /** The depth at which aim guard is active (null when not guarding) */
+    guardedDepthRef: React.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.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.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.MouseEventHandler<HTMLDivElement>;
+        onPointerMove: React.PointerEventHandler<HTMLDivElement>;
+        onPointerDown: React.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;
+
+export { type AimGuardRefs as A, type GroupContextValue as G, type ItemContextValue as I, type UseListboxItemParams as U, useMaybeItemContext as a, type GroupPositional as b, GroupContext as c, useGroupContext as d, ItemContext as e, type UseListboxItemReturn as f, useListboxItem as g, useItemContext as u };