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

package/dist/combobox/index.d.cts

@@ -0,0 +1,1039 @@
+import { V as VirtualItem } from '../ListboxStore-BtcTXpzi.cjs';
+export { F as ComboboxFilterFn, I as ComboboxItemRegistration, b as ComboboxStore, L as ComboboxStoreContext, a as ComboboxStoreState } from '../ListboxStore-BtcTXpzi.cjs';
+import { P as PopupMenuDebugOptions, a as PopupMenuRootActions, n as PopupMenuSurface, J as PopupMenuSurfaceProps, b as PopupMenuArrow, c as PopupMenuBackdrop, d as PopupMenuEmpty, e as PopupMenuGroup, f as PopupMenuGroupLabel, g as PopupMenuIcon, h as PopupMenuList, i as PopupMenuPopup, j as PopupMenuPortal, k as PopupMenuScrollDownArrow, l as PopupMenuScrollUpArrow, m as PopupMenuSeparator } from '../separator-BmbUeeaT.cjs';
+export { o as ComboboxArrowProps, p as ComboboxBackdropProps, q as ComboboxEmptyProps, r as ComboboxEmptyState, s as ComboboxGroupLabelProps, t as ComboboxGroupLabelState, u as ComboboxGroupProps, v as ComboboxGroupState, w as ComboboxIconProps, x as ComboboxIconState, y as ComboboxListChildrenState, L as ComboboxListCssVars, z as ComboboxListProps, A as ComboboxListState, B as ComboboxPopupProps, C as ComboboxPortalProps, M as ComboboxPositionerCssVars, D as ComboboxScrollArrowProps, E as ComboboxScrollArrowState, F as ComboboxScrollDownArrowProps, G as ComboboxScrollUpArrowProps, H as ComboboxSeparatorProps, I as ComboboxSeparatorState, K as ComboboxSurfaceState } from '../separator-BmbUeeaT.cjs';
+import * as React from 'react';
+import { C as ComponentProps } from '../types-9vS1uLIK.cjs';
+import { PopoverPositionerProps, Popover, PopoverRootProps } from '@base-ui/react/popover';
+import { I as ItemEqualityComparer } from '../item-equality-B6TbXlBT.cjs';
+import { C as ChangeEventDetails, t as triggerPress, e as escapeKey, o as outsidePress, f as focusOut, i as itemPress, h as inputChange, j as inputClear, l as listNavigation, g as imperativeAction, n as none, G as GenericEventDetails, p as pointer, k as keyboard } from '../events-BPr8sRGH.cjs';
+export { S as SurfaceContextValue, c as commandScore, d as defaultFilter, u as useMaybeSurfaceContext, a as useSurfaceContext } from '../command-score-YjNr3ZWi.cjs';
+import '@base-ui/utils/store';
+
+interface ComboboxClearState extends Record<string, unknown> {
+    /**
+     * Whether the combobox has a value (clear button is actionable).
+     */
+    hasValue: boolean;
+    /**
+     * Whether the combobox is disabled.
+     */
+    disabled: boolean;
+}
+interface ComboboxClearProps extends ComponentProps<'button', ComboboxClear.State> {
+    /**
+     * Whether to render the button even when there's no value to clear.
+     * @default false
+     */
+    keepMounted?: boolean;
+}
+/**
+ * A button that clears the selected value(s) when clicked.
+ * Renders a `<button>` element.
+ */
+declare const ComboboxClear: React.ForwardRefExoticComponent<Omit<ComboboxClear.Props, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+declare namespace ComboboxClear {
+    type State = ComboboxClearState;
+    interface Props extends ComboboxClearProps {
+    }
+}
+
+type Side = 'top' | 'bottom' | 'left' | 'right';
+type Align = 'start' | 'center' | 'end';
+/**
+ * Layout mode for the combobox popup.
+ * - `'floating'` - Standard dropdown positioning below/above the input
+ * - `'input-embedded'` - Popup wraps around the input (macOS-style)
+ */
+type ComboboxLayout = 'floating' | 'input-embedded';
+/**
+ * Context value for Combobox Positioner.
+ * Provides alignment state for coordinating positioning behavior.
+ */
+interface ComboboxPositionerContextValue {
+    /**
+     * The layout mode being used.
+     * - `'floating'` - Standard dropdown positioning
+     * - `'input-embedded'` - Popup wraps around the input
+     */
+    layout: ComboboxLayout;
+    /**
+     * The side of the popup relative to the input.
+     */
+    side: Side;
+    /**
+     * The alignment of the popup.
+     */
+    align: Align;
+    /**
+     * Height of the input element in pixels.
+     * Use this to add appropriate padding to the popup.
+     */
+    inputHeight: number;
+}
+/**
+ * Hook to access the Combobox Positioner context.
+ * Returns null if used outside a ComboboxPositioner.
+ */
+declare function useComboboxPositionerContext(): ComboboxPositionerContextValue | null;
+
+/**
+ * Data attributes for ComboboxInput component.
+ */
+declare const ComboboxInputDataAttributes: {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-input'}
+     */
+    readonly slot: "bazzaui-combobox-input";
+    /** Present when the combobox popup is open. */
+    readonly open: "data-open";
+    /** Present when the combobox popup is closed. */
+    readonly closed: "data-closed";
+    /** Present when the input is disabled. */
+    readonly disabled: "data-disabled";
+    /** Present when no value is selected (showing placeholder). */
+    readonly placeholder: "data-placeholder";
+};
+
+interface ComboboxInputState extends Record<string, unknown> {
+    /**
+     * Whether the combobox popup is open.
+     */
+    open: boolean;
+    /**
+     * Whether the input is disabled.
+     */
+    disabled: boolean;
+    /**
+     * Whether the input currently shows placeholder (no value selected).
+     */
+    placeholder: boolean;
+}
+/**
+ * Cursor behavior when the combobox popup opens.
+ * - `'none'` - Don't move the cursor (cursor appears where clicked)
+ * - `'end'` - Move cursor to the end of the input
+ * - `'select-all'` - Move cursor to the end and select all text
+ */
+type ComboboxInputCursorBehavior = 'none' | 'end' | 'select-all';
+interface ComboboxInputProps extends Omit<ComponentProps<'input', ComboboxInput.State>, 'value' | 'onChange' | 'type'> {
+    /**
+     * Placeholder text shown when no value is selected and input is empty.
+     * Overrides the placeholder set on Combobox.Root.
+     */
+    placeholder?: string;
+    /**
+     * Cursor behavior when the combobox popup opens.
+     * - `'none'` - Don't move the cursor (cursor appears where clicked)
+     * - `'end'` - Move cursor to the end of the input
+     * - `'select-all'` - Move cursor to the end and select all text
+     *
+     * @default 'none'
+     */
+    cursorBehavior?: ComboboxInputCursorBehavior;
+}
+/**
+ * An input that acts as both the trigger and search field for the combobox.
+ * Renders an `<input>` element with combobox ARIA semantics.
+ */
+declare const ComboboxInput: React.ForwardRefExoticComponent<Omit<ComboboxInput.Props, "ref"> & React.RefAttributes<HTMLInputElement>>;
+declare namespace ComboboxInput {
+    interface Props extends ComboboxInputProps {
+    }
+    type State = ComboboxInputState;
+}
+
+/**
+ * Data attributes for ComboboxInputWrapper component.
+ */
+declare const ComboboxInputWrapperDataAttributes: {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-input-wrapper'}
+     */
+    readonly slot: "bazzaui-combobox-input-wrapper";
+    /** Present when the combobox popup is open. */
+    readonly open: "data-open";
+};
+
+interface ComboboxInputWrapperState extends Record<string, unknown> {
+    /**
+     * Whether the combobox popup is open.
+     */
+    open: boolean;
+}
+interface ComboboxInputWrapperProps extends ComponentProps<'div', ComboboxInputWrapper.State> {
+}
+/**
+ * A wrapper component for the Combobox.Input and Combobox.Icon.
+ * Provides relative positioning context and manages z-index for input-embedded layouts.
+ * Use this to position icons or other elements inside/over the input.
+ *
+ * Renders a `<div>` element with `position: relative`.
+ */
+declare const ComboboxInputWrapper: React.ForwardRefExoticComponent<Omit<ComboboxInputWrapper.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace ComboboxInputWrapper {
+    type State = ComboboxInputWrapperState;
+    interface Props extends ComboboxInputWrapperProps {
+    }
+}
+
+/**
+ * Data attributes applied to Combobox.Item for styling.
+ *
+ * @example
+ * ```css
+ * [data-bazzaui-combobox-item][data-highlighted] {
+ *   background: var(--highlight-bg);
+ * }
+ * [data-bazzaui-combobox-item][data-selected] {
+ *   font-weight: bold;
+ * }
+ * [data-bazzaui-combobox-item][data-disabled] {
+ *   opacity: 0.5;
+ *   pointer-events: none;
+ * }
+ * ```
+ */
+declare const ComboboxItemDataAttributes: {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-item'}
+     */
+    readonly slot: "bazzaui-combobox-item";
+    /** Present when the item is highlighted (via keyboard or pointer). */
+    readonly highlighted: "data-highlighted";
+    /** Present when the item is disabled. */
+    readonly disabled: "data-disabled";
+    /** Present when the item is currently selected. */
+    readonly selected: "data-selected";
+};
+
+interface ComboboxItemState 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.
+     */
+    selected: boolean;
+}
+interface ComboboxItemProps<Value = unknown> extends ComponentProps<'div', ComboboxItem.State> {
+    /**
+     * The value of this item. Required and must be unique within the Combobox.
+     * Can be a primitive or an object.
+     */
+    value: Value;
+    /**
+     * Text value to use for display in the input when this item is selected.
+     * If not provided, the text content of the item will be used.
+     * For object values, this can be auto-detected from `{ label }` shape.
+     */
+    textValue?: string;
+    /**
+     * Additional keywords to match against when filtering.
+     * Useful for aliases or synonyms.
+     */
+    keywords?: string[];
+    /**
+     * Whether this item is disabled.
+     * Disabled items are not selectable and are skipped during keyboard navigation.
+     */
+    disabled?: boolean;
+    /**
+     * Callback when this item is selected.
+     */
+    onSelect?: () => void;
+    /**
+     * Whether to force render this item regardless of filter results.
+     * @default false
+     */
+    forceMount?: boolean;
+}
+declare const ComboboxItem: <Value = unknown>(props: ComboboxItemProps<Value> & React.RefAttributes<HTMLDivElement>) => React.ReactElement | null;
+declare namespace ComboboxItem {
+    type State = ComboboxItemState;
+    interface Props<Value = unknown> extends ComboboxItemProps<Value> {
+    }
+}
+
+/**
+ * Data attributes for ComboboxItemIndicator component.
+ */
+declare const ComboboxItemIndicatorDataAttributes: {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-item-indicator'}
+     */
+    readonly slot: "bazzaui-combobox-item-indicator";
+    /** Present when the item is selected. */
+    readonly selected: "data-selected";
+};
+
+interface ComboboxItemIndicatorState extends Record<string, unknown> {
+    /**
+     * Whether the parent item is selected.
+     */
+    selected: boolean;
+}
+interface ComboboxItemIndicatorProps extends ComponentProps<'span', ComboboxItemIndicator.State> {
+    /**
+     * Whether to always render the indicator regardless of selection state.
+     * When false (default), only renders when the item is selected.
+     * @default false
+     */
+    keepMounted?: boolean;
+}
+/**
+ * Visual indicator for the selected state of a combobox item.
+ * Only renders when the parent item is selected (unless keepMounted is true).
+ * Renders a `<span>` element.
+ */
+declare const ComboboxItemIndicator: React.ForwardRefExoticComponent<Omit<ComboboxItemIndicator.Props, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare namespace ComboboxItemIndicator {
+    type State = ComboboxItemIndicatorState;
+    interface Props extends ComboboxItemIndicatorProps {
+    }
+}
+
+interface ComboboxItemLabelState extends Record<string, unknown> {
+    /**
+     * The serialized string key for the parent item's value.
+     * For object values, this is the result of `itemToStringValue` or the auto-detected `.value` property.
+     */
+    value: string;
+    /**
+     * Whether the parent item is selected.
+     */
+    selected: boolean;
+    /**
+     * Whether the parent item is highlighted.
+     */
+    highlighted: boolean;
+    /**
+     * Whether the parent item is disabled.
+     */
+    disabled: boolean;
+}
+interface ComboboxItemLabelProps extends ComponentProps<'span', ComboboxItemLabel.State> {
+}
+/**
+ * Renders the text label for a combobox item.
+ *
+ * When no children are provided, automatically renders the label from:
+ * 1. The `items` prop passed to `Combobox.Root`
+ * 2. The `textValue` prop on `Combobox.Item`
+ * 3. Falls back to the item's value
+ *
+ * Also registers the text content for use in the input display.
+ * Renders a `<span>` element.
+ */
+declare const ComboboxItemLabel: React.ForwardRefExoticComponent<Omit<ComboboxItemLabel.Props, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+declare namespace ComboboxItemLabel {
+    interface Props extends ComboboxItemLabelProps {
+    }
+    type State = ComboboxItemLabelState;
+}
+
+/**
+ * Data attributes for ComboboxPositioner component.
+ */
+declare const ComboboxPositionerDataAttributes: {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-positioner'}
+     */
+    readonly slot: "bazzaui-combobox-positioner";
+};
+
+interface ComboboxPositionerProps extends PopoverPositionerProps {
+    /**
+     * Override the layout mode for the popup.
+     * If not provided, uses the `layout` from `Combobox.Root`.
+     *
+     * - `'floating'` - Standard dropdown positioning below/above the input
+     * - `'input-embedded'` - Popup wraps around the input (macOS Spotlight-style).
+     *   The input appears to be inside the popup at the top.
+     *
+     * When `'input-embedded'`:
+     * - Popup is positioned flush with the input (sideOffset=0)
+     * - Alignment is centered on the input
+     * - Positioning styles are automatically applied to the Popup child
+     * - Use `popupPadding` to control the padding around the input
+     * - `data-input-embedded` attribute is added to Input, Positioner, Popup, and List
+     */
+    layout?: ComboboxLayout;
+    /**
+     * Padding around the popup content when `layout="input-embedded"`.
+     * Creates the "encapsulated" look where the input appears inside the popup
+     * with padding on all sides.
+     *
+     * Only applies when `layout="input-embedded"`.
+     *
+     * @default 8
+     */
+    popupPadding?: number;
+}
+/**
+ * Positions the combobox popup against the input.
+ * Uses the input element as the anchor for positioning.
+ *
+ * Supports `alignInputWithPopup` mode where the popup visually wraps around
+ * the input, making the input appear to be inside the popup (macOS-style).
+ *
+ * Renders a `<div>` element.
+ */
+declare const ComboboxPositioner: React.ForwardRefExoticComponent<ComboboxPositionerProps & React.RefAttributes<HTMLDivElement>>;
+declare namespace ComboboxPositioner {
+    type Props = ComboboxPositionerProps;
+    type State = Popover.Positioner.State;
+}
+
+/**
+ * Reasons why the combobox's open state changed.
+ */
+type ComboboxOpenChangeReason = typeof triggerPress | typeof escapeKey | typeof outsidePress | typeof focusOut | typeof itemPress | typeof inputChange | typeof inputClear | typeof listNavigation | typeof imperativeAction | typeof none;
+/**
+ * Event details passed to the `onOpenChange` callback.
+ */
+type ComboboxOpenChangeEventDetails = ChangeEventDetails<ComboboxOpenChangeReason>;
+/**
+ * Reasons why highlight changed.
+ */
+type ComboboxHighlightChangeReason = typeof pointer | typeof keyboard | typeof none;
+/**
+ * Event details passed to the `onHighlightChange` callback.
+ */
+type ComboboxHighlightChangeEventDetails = GenericEventDetails<ComboboxHighlightChangeReason, {
+    index: number;
+}>;
+
+/**
+ * Helper type to determine the value type based on the multiple flag.
+ */
+type ComboboxValueType<Value, Multiple extends boolean | undefined> = Multiple extends true ? Value[] : Value | null;
+interface ComboboxRootProps<Value = unknown, Multiple extends boolean | undefined = false> extends Omit<PopoverRootProps, 'open' | 'onOpenChange' | 'defaultOpen' | 'actionsRef'> {
+    /**
+     * Whether the combobox 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: ComboboxOpenChangeEventDetails) => void;
+    /**
+     * Whether the combobox is initially open.
+     * Use for uncontrolled mode.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * A ref to imperative actions.
+     * - `close`: closes the menu imperatively.
+     * - `unmount`: unmounts the popup imperatively (when keep-mounted mode is enabled).
+     * - `setDisabled`: enables/disables the menu imperatively.
+     */
+    actionsRef?: React.RefObject<ComboboxRoot.Actions | null>;
+    /**
+     * Current selected value (single-select mode).
+     * Use for controlled mode.
+     * Can be a primitive or an object.
+     */
+    value?: ComboboxValueType<Value, Multiple>;
+    /**
+     * Default selected value (single-select mode).
+     * Use for uncontrolled mode.
+     */
+    defaultValue?: ComboboxValueType<Value, Multiple>;
+    /**
+     * Callback when the selected value changes (single-select mode).
+     */
+    onValueChange?: (value: Value) => void;
+    /**
+     * Whether multi-select mode is enabled.
+     * @default false
+     */
+    multiple?: Multiple;
+    /**
+     * Current selected values (multi-select mode).
+     * Use for controlled mode.
+     */
+    values?: Value[];
+    /**
+     * Default selected values (multi-select mode).
+     * Use for uncontrolled mode.
+     */
+    defaultValues?: Value[];
+    /**
+     * Callback when the selected values change (multi-select mode).
+     */
+    onValuesChange?: (values: Value[]) => void;
+    /**
+     * Custom comparison logic used to determine if a combobox item value
+     * matches the current selected value.
+     * Useful when item values are objects without matching referentially.
+     * Defaults to Object.is comparison.
+     */
+    isItemEqualToValue?: ItemEqualityComparer<Value>;
+    /**
+     * When the item values are objects (`<Combobox.Item value={object}>`),
+     * this function converts the object value to a string representation
+     * for display in the input.
+     * If the shape of the object is `{ value, label }`, the label will be
+     * used automatically without needing to specify this prop.
+     */
+    itemToStringLabel?: (itemValue: Value) => string;
+    /**
+     * When the item values are objects (`<Combobox.Item value={object}>`),
+     * this function converts the object value to a string representation
+     * for form submission.
+     * If the shape of the object is `{ value, label }`, the value will be
+     * used automatically without needing to specify this prop.
+     */
+    itemToStringValue?: (itemValue: Value) => string;
+    /**
+     * Current input value.
+     * Use for controlled mode.
+     */
+    inputValue?: string;
+    /**
+     * Default input value.
+     * Use for uncontrolled mode.
+     */
+    defaultInputValue?: string;
+    /**
+     * Callback when the input value changes.
+     */
+    onInputValueChange?: (value: string) => void;
+    /**
+     * Form field name for submission.
+     * When set, hidden input(s) will be rendered for form submission.
+     */
+    name?: string;
+    /**
+     * Associate with a form by ID.
+     */
+    form?: string;
+    /**
+     * Whether this field is required.
+     */
+    required?: boolean;
+    /**
+     * Whether the combobox is disabled.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Placeholder text for the input.
+     * @default "Search..."
+     */
+    placeholder?: string;
+    /**
+     * Data structure of the items rendered in the combobox popup.
+     * When specified, the input shows the label of the selected item
+     * instead of the raw value.
+     *
+     * Can be a record mapping values to labels, or an array of { value, label } objects.
+     * @example
+     * ```tsx
+     * // Record format
+     * <Combobox.Root items={{ us: 'United States', uk: 'United Kingdom' }}>
+     *
+     * // Array format
+     * <Combobox.Root items={[
+     *   { value: 'us', label: 'United States' },
+     *   { value: 'uk', label: 'United Kingdom' },
+     * ]}>
+     * ```
+     */
+    items?: Record<string, React.ReactNode> | Array<{
+        value: string;
+        label: React.ReactNode;
+    }>;
+    /**
+     * Determines if the combobox enters a modal state when open.
+     *
+     * - `true`: user interaction is limited to the combobox: document page scroll
+     *   is locked, and pointer interactions on outside elements are disabled.
+     * - `false`: user interaction with the rest of the document is allowed.
+     * - `'trap-focus'`: focus is trapped inside the combobox, but document page
+     *   scroll is not locked and pointer interactions outside of it remain enabled.
+     *
+     * @default false
+     */
+    modal?: boolean | 'trap-focus';
+    /**
+     * Whether to close the popup after selecting an item.
+     * @default true for single-select, false for multi-select
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Whether to open the popup when the input is focused.
+     * @default true
+     */
+    openOnFocus?: boolean;
+    /**
+     * Whether virtualization mode is enabled.
+     * When true, items should provide an explicit `index` prop and
+     * the `virtualItems` 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.
+     */
+    virtualItems?: VirtualItem[];
+    /**
+     * Callback when the highlighted item changes.
+     * Useful for synchronizing with a virtualizer (e.g., scrollToIndex) or other UI state.
+     * The third parameter contains event details including the reason for the change.
+     */
+    onHighlightChange?: (id: string | null, index: number, eventDetails: ComboboxHighlightChangeEventDetails) => void;
+    /**
+     * The layout mode for the combobox popup.
+     *
+     * - `'floating'` (default) - Standard dropdown positioning below/above the input
+     * - `'input-embedded'` - Popup wraps around the input (macOS Spotlight-style).
+     *   The input appears to be inside the popup at the top.
+     *
+     * When `'input-embedded'`:
+     * - `data-input-embedded` attribute is added to Input, Positioner, Popup, and List
+     * - Use CSS selectors like `[data-input-embedded]` to style components
+     *
+     * @default 'floating'
+     */
+    layout?: ComboboxLayout;
+    /**
+     * 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;
+    /**
+     * Debug visualization options for submenu interaction heuristics.
+     */
+    debug?: PopupMenuDebugOptions;
+    children: React.ReactNode;
+}
+/**
+ * Groups all parts of the combobox.
+ * Manages open state, selection state, input state, and provides context to children.
+ * Doesn't render its own HTML element.
+ *
+ * @template Value - The type of the combobox value (can be a primitive or object)
+ * @template Multiple - Whether multiple selection is enabled
+ */
+declare function ComboboxRoot<Value = unknown, Multiple extends boolean | undefined = false>(props: ComboboxRootProps<Value, Multiple>): React.JSX.Element;
+declare namespace ComboboxRoot {
+    interface Props<Value = unknown, Multiple extends boolean | undefined = false> extends ComboboxRootProps<Value, Multiple> {
+    }
+    type OpenChangeEventDetails = ComboboxOpenChangeEventDetails;
+    type HighlightChangeEventDetails = ComboboxHighlightChangeEventDetails;
+    type Actions = PopupMenuRootActions;
+}
+
+interface ComboboxSurfaceProps extends Omit<PopupMenuSurfaceProps, 'autoHighlightFirst'> {
+    /**
+     * Controls auto-highlighting behavior when the combobox opens.
+     * - `true`: highlight the first item (default)
+     * - `false`: don't auto-highlight any item
+     * - `'selected'`: highlight the currently selected item, or first item if none selected
+     * - `string`: highlight the item with this specific value
+     * @default true
+     */
+    autoHighlightFirst?: boolean | 'selected' | string;
+}
+/**
+ * Provides search context and manages item registration for Combobox.
+ * Automatically syncs the search state with the combobox's input value.
+ *
+ * Place inside Combobox.Popup to enable search functionality.
+ * Renders a `<div>` element.
+ */
+declare const ComboboxSurface: React.ForwardRefExoticComponent<Omit<ComboboxSurface.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare namespace ComboboxSurface {
+    type State = PopupMenuSurface.State;
+    interface Props extends ComboboxSurfaceProps {
+    }
+}
+
+declare const index_parts_VirtualItem: typeof VirtualItem;
+declare const index_parts_useComboboxPositionerContext: typeof useComboboxPositionerContext;
+declare namespace index_parts {
+  export { PopupMenuArrow as Arrow, PopupMenuBackdrop as Backdrop, ComboboxClear as Clear, PopupMenuEmpty as Empty, PopupMenuGroup as Group, PopupMenuGroupLabel as GroupLabel, PopupMenuIcon as Icon, ComboboxInput as Input, ComboboxInputWrapper as InputWrapper, ComboboxItem as Item, ComboboxItemIndicator as ItemIndicator, ComboboxItemLabel as ItemLabel, PopupMenuList as List, PopupMenuPopup as Popup, PopupMenuPortal as Portal, ComboboxPositioner as Positioner, ComboboxRoot as Root, PopupMenuScrollDownArrow as ScrollDownArrow, PopupMenuScrollUpArrow as ScrollUpArrow, PopupMenuSeparator as Separator, ComboboxSurface as Surface, index_parts_VirtualItem as VirtualItem, index_parts_useComboboxPositionerContext as useComboboxPositionerContext };
+}
+
+declare enum ComboboxArrowDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-arrow'}
+     */
+    slot = "bazzaui-combobox-arrow",
+    /**
+     * Present when the popup menu is open.
+     */
+    open = "data-open",
+    /**
+     * Present when the popup menu is closed.
+     */
+    closed = "data-closed",
+    /**
+     * Indicates which side the popup is positioned relative to the trigger.
+     * @type {'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'}
+     */
+    side = "data-side",
+    /**
+     * Indicates how the popup is aligned relative to specified side.
+     * @type {'start' | 'center' | 'end'}
+     */
+    align = "data-align",
+    /**
+     * Present when the arrow is not centered due to collision avoidance.
+     */
+    uncentered = "data-uncentered"
+}
+
+declare enum ComboboxBackdropDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-backdrop'}
+     */
+    slot = "bazzaui-combobox-backdrop",
+    /**
+     * Present when the popup menu is open.
+     */
+    open = "data-open",
+    /**
+     * Present when the popup menu is closed.
+     */
+    closed = "data-closed",
+    /**
+     * Present when the popup menu is animating in.
+     */
+    startingStyle = "data-starting-style",
+    /**
+     * Present when the popup menu is animating out.
+     */
+    endingStyle = "data-ending-style"
+}
+
+declare enum ComboboxEmptyDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-empty'}
+     */
+    slot = "bazzaui-combobox-empty"
+}
+
+declare enum ComboboxGroupDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-group'}
+     */
+    slot = "bazzaui-combobox-group"
+}
+
+declare enum ComboboxGroupLabelDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-group-label'}
+     */
+    slot = "bazzaui-combobox-group-label"
+}
+
+declare const ComboboxIconDataAttributes: {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-icon'}
+     */
+    readonly slot: "bazzaui-combobox-icon";
+    /** Present when the popup is open. */
+    readonly open: "data-popup-open";
+};
+
+declare enum ComboboxListDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-list'}
+     */
+    slot = "bazzaui-combobox-list",
+    /**
+     * Always present on the list element.
+     * Used for styling and by useStickyRowWidth to find the list container.
+     */
+    list = "data-popup-menu-list"
+}
+
+declare enum ComboboxPopupDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-popup'}
+     */
+    slot = "bazzaui-combobox-popup",
+    /**
+     * Present when the popup menu is open.
+     */
+    open = "data-open",
+    /**
+     * Present when the popup menu is closed.
+     */
+    closed = "data-closed",
+    /**
+     * Indicates which side the popup is positioned relative to the trigger.
+     * @type {'top' | 'bottom' | 'left' | 'right'}
+     */
+    side = "data-side",
+    /**
+     * Indicates how the popup is aligned relative to specified side.
+     * @type {'start' | 'center' | 'end'}
+     */
+    align = "data-align",
+    /**
+     * Present when the popup is animating in.
+     */
+    startingStyle = "data-starting-style",
+    /**
+     * Present when the popup is animating out.
+     */
+    endingStyle = "data-ending-style",
+    /**
+     * Present if animations should be instant.
+     * @type {'click' | 'dismiss'}
+     */
+    instant = "data-instant",
+    /**
+     * Present when this popup's surface is the focus owner.
+     * Useful for styling the currently focused menu in a submenu chain.
+     */
+    focused = "data-focused",
+    /**
+     * Present when this popup has an open submenu below it in the menu tree.
+     * Useful for styling all parent menus in an open submenu chain.
+     */
+    hasOpenSubmenu = "data-has-open-submenu",
+    /**
+     * Present when this popup is a submenu (not the root menu).
+     * Useful for applying different styles to submenus vs root menus.
+     */
+    submenu = "data-submenu",
+    /**
+     * Present while navigating between subpages in this popup.
+     * Useful for temporary transition adjustments during subpage focus handoff.
+     */
+    navigating = "data-navigating"
+}
+
+declare const ComboboxScrollArrowDataAttributes: {
+    /**
+     * Identifies the component part for scroll up arrow.
+     * @type {'bazzaui-combobox-scroll-up-arrow'}
+     */
+    readonly slotUp: "bazzaui-combobox-scroll-up-arrow";
+    /**
+     * Identifies the component part for scroll down arrow.
+     * @type {'bazzaui-combobox-scroll-down-arrow'}
+     */
+    readonly slotDown: "bazzaui-combobox-scroll-down-arrow";
+    /**
+     * Direction of the scroll arrow.
+     * @type {'up' | 'down'}
+     */
+    readonly direction: "data-direction";
+    /**
+     * Side of the popup.
+     * @type {'top' | 'bottom' | 'left' | 'right'}
+     */
+    readonly side: "data-side";
+};
+
+declare enum ComboboxSeparatorDataAttributes {
+    /**
+     * Identifies the component part.
+     * @type {'bazzaui-combobox-separator'}
+     */
+    slot = "bazzaui-combobox-separator"
+}
+
+/**
+ * Filter mode for the combobox.
+ * Controls how the search/filter value is determined.
+ *
+ * State transitions:
+ * - Closed → open (no value) → { type: 'active' }
+ * - Closed → open (with value) → { type: 'showAll' }
+ * - Open + user types → { type: 'active' }
+ * - Open → close → { type: 'frozen', search: <current> }
+ */
+type ComboboxFilterMode = {
+    type: 'active';
+} | {
+    type: 'showAll';
+} | {
+    type: 'frozen';
+    search: string;
+};
+/**
+ * Item text registry for displaying selected values.
+ * Maps serialized item value to its text content.
+ */
+type ItemTextRegistry = Map<string, string>;
+/**
+ * Context value for Combobox components.
+ * Provides value state, input state, callbacks, and form integration.
+ *
+ * @template Value - The type of the combobox value (can be a primitive or object)
+ */
+interface ComboboxContextValue<Value = unknown> {
+    /** Whether multi-select mode is enabled */
+    multiple: boolean;
+    /** Current selected value (single-select mode) */
+    value: Value | null;
+    /** Current selected values (multi-select mode) */
+    values: Value[];
+    /** Callback when value changes (single-select mode) */
+    onValueChange: (value: Value) => void;
+    /** Callback when values change (multi-select mode) */
+    onValuesChange: (values: Value[]) => void;
+    /**
+     * Custom comparison logic used to determine if a combobox item value
+     * matches the current selected value.
+     * Useful when item values are objects without matching referentially.
+     * Defaults to Object.is comparison.
+     */
+    isItemEqualToValue: ItemEqualityComparer<Value>;
+    /**
+     * When the item values are objects, this function converts the object
+     * value to a string representation for display in the input.
+     * If the shape of the object is { value, label }, the label will be
+     * used automatically without needing to specify this prop.
+     */
+    itemToStringLabel?: (itemValue: Value) => string;
+    /**
+     * When the item values are objects, this function converts the object
+     * value to a string representation for form submission.
+     * If the shape of the object is { value, label }, the value will be
+     * used automatically without needing to specify this prop.
+     */
+    itemToStringValue?: (itemValue: Value) => string;
+    /** Current input value */
+    inputValue: string;
+    /** Callback when input value changes */
+    onInputValueChange: (value: string) => void;
+    /** Form field name for submission */
+    name?: string;
+    /** Associate with a form by ID */
+    form?: string;
+    /** Whether this field is required */
+    required?: boolean;
+    /** Whether the combobox is disabled */
+    disabled: boolean;
+    /** Placeholder text for the input */
+    placeholder: string;
+    /** Registry of item values to their text content */
+    itemTextRegistry: ItemTextRegistry;
+    /** Register an item's text content */
+    registerItemText: (value: string, text: string) => () => void;
+    /**
+     * Data structure of the items for label resolution.
+     * Used to display labels before items mount (e.g., on initial render with defaultValue).
+     * Can be a record mapping values to labels, or an array of { value, label } objects.
+     */
+    items?: Record<string, React.ReactNode> | Array<{
+        value: string;
+        label: React.ReactNode;
+    }>;
+    /** ID for the listbox element */
+    listId: string;
+    /** Ref to the input element (also serves as anchor) */
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    /** Callback to set the input element */
+    setInputElement: (element: HTMLInputElement | null) => void;
+    /** Ref to the input wrapper element (used as anchor when present) */
+    inputWrapperRef: React.RefObject<HTMLElement | null>;
+    /** Callback to set the input wrapper element */
+    setInputWrapperElement: (element: HTMLElement | null) => void;
+    /** Whether to close on selection (default: true for single, false for multiple) */
+    closeOnSelect: boolean;
+    /** Whether to open on focus */
+    openOnFocus: boolean;
+    /** Open the combobox */
+    openCombobox: () => void;
+    /** Close the combobox with an optional reason and event */
+    closeCombobox: (reason?: ComboboxOpenChangeReason, event?: Event) => void;
+    /**
+     * Current filter mode for the combobox.
+     * Controls how the search/filter value is determined.
+     */
+    filterMode: ComboboxFilterMode;
+    /** Set the filter mode to 'active' (normal filtering using inputValue) */
+    setFilterActive: () => void;
+    /**
+     * Height of the input element in pixels.
+     * Used by the positioner for input-embedded layout calculations.
+     */
+    inputHeight: number;
+    /**
+     * Width of the input element in pixels.
+     * Used by the positioner for input-embedded layout calculations.
+     */
+    inputWidth: number;
+    /**
+     * The layout mode for the combobox popup.
+     * - `'floating'` - Standard dropdown positioning
+     * - `'input-embedded'` - Popup wraps around the input (macOS-style)
+     */
+    layout: ComboboxLayout;
+}
+/**
+ * Hook to access the Combobox context.
+ * Throws if used outside a Combobox.Root.
+ */
+declare function useComboboxContext<Value = unknown>(): ComboboxContextValue<Value>;
+/**
+ * Hook to optionally access the Combobox context.
+ * Returns null if used outside a Combobox.Root.
+ */
+declare function useMaybeComboboxContext<Value = unknown>(): ComboboxContextValue<Value> | null;
+
+/**
+ * Context value for ComboboxItem.
+ * Provides item state to child components like ItemIndicator.
+ *
+ * @template Value - The type of the item value (can be a primitive or object)
+ */
+interface ComboboxItemContextValue<Value = unknown> {
+    /** Unique ID for the item element */
+    id: string;
+    /** The item's value */
+    value: Value;
+    /** The text value/label for this item */
+    textValue: string | undefined;
+    /** Whether the item is highlighted (via keyboard or pointer) */
+    highlighted: boolean;
+    /** Whether the item is disabled */
+    disabled: boolean;
+    /** Whether the item is selected */
+    selected: boolean;
+}
+/**
+ * Hook to access the ComboboxItem context.
+ * Throws if used outside a ComboboxItem.
+ */
+declare function useComboboxItemContext<Value = unknown>(): ComboboxItemContextValue<Value>;
+/**
+ * Hook to optionally access the ComboboxItem context.
+ * Returns null if used outside a ComboboxItem.
+ */
+declare function useMaybeComboboxItemContext<Value = unknown>(): ComboboxItemContextValue<Value> | null;
+
+export { index_parts as Combobox, PopupMenuArrow as ComboboxArrow, ComboboxArrowDataAttributes, PopupMenuBackdrop as ComboboxBackdrop, ComboboxBackdropDataAttributes, ComboboxClear, type ComboboxClearProps, type ComboboxClearState, type ComboboxContextValue, PopupMenuEmpty as ComboboxEmpty, ComboboxEmptyDataAttributes, PopupMenuGroup as ComboboxGroup, ComboboxGroupDataAttributes, PopupMenuGroupLabel as ComboboxGroupLabel, ComboboxGroupLabelDataAttributes, ComboboxIconDataAttributes, ComboboxInput, type ComboboxInputCursorBehavior, ComboboxInputDataAttributes, type ComboboxInputProps, type ComboboxInputState, ComboboxInputWrapper, ComboboxInputWrapperDataAttributes, type ComboboxInputWrapperProps, type ComboboxInputWrapperState, ComboboxItem, type ComboboxItemContextValue, ComboboxItemDataAttributes, ComboboxItemIndicator, ComboboxItemIndicatorDataAttributes, type ComboboxItemIndicatorProps, type ComboboxItemIndicatorState, ComboboxItemLabel, type ComboboxItemLabelProps, type ComboboxItemProps, type ComboboxItemState, type ComboboxLayout, PopupMenuList as ComboboxList, ComboboxListDataAttributes, PopupMenuPopup as ComboboxPopup, ComboboxPopupDataAttributes, PopupMenuPortal as ComboboxPortal, ComboboxPositioner, type ComboboxPositionerContextValue, ComboboxPositionerDataAttributes, type ComboboxPositionerProps, ComboboxRoot, type ComboboxRootProps, ComboboxScrollArrowDataAttributes, PopupMenuSeparator as ComboboxSeparator, ComboboxSeparatorDataAttributes, ComboboxSurface, type ComboboxSurfaceProps, VirtualItem as ComboboxVirtualItem, useComboboxContext, useComboboxItemContext, useComboboxPositionerContext, useMaybeComboboxContext, useMaybeComboboxItemContext };