@arun-dev/headless 4.7.0 → 4.9.0

package/dist/combobox/index.d.cts

@@ -0,0 +1,322 @@
+import * as react from 'react';
+import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
+import { A as AnchorSide, a as AnchorAlign } from '../anchoring-Btxi0QwC.cjs';
+
+/** Why a value, the input's text or the open state changed — the second callback argument. */
+type ComboboxChangeReason = 'input' | 'input-press' | 'trigger-press' | 'item-press' | 'keyboard' | 'clear' | 'chip-remove' | 'escape' | 'outside-press' | 'blur' | 'form-reset';
+type ComboboxChangeDetails = {
+    reason: ComboboxChangeReason;
+};
+/** Why the highlighted item changed: arrow keys, the pointer, or the component itself. */
+type ComboboxHighlightReason = 'keyboard' | 'pointer' | 'none';
+type ComboboxHighlightDetails = {
+    index: number;
+    reason: ComboboxHighlightReason;
+};
+/** The state Combobox.Root shares with its parts, and projects as `data-*` attributes. */
+type ComboboxState = {
+    open: boolean;
+    multiple: boolean;
+    disabled: boolean;
+};
+
+/** The selection: one item or `null`, or an array with `multiple`. */
+type ComboboxValue$1<T, Multiple extends boolean> = Multiple extends true ? T[] : T | null;
+/** Takes the whole list, so a filter can rank as well as narrow — a fuzzy search, say. */
+type ComboboxFilter<T> = (items: readonly T[], query: string, itemToString: (item: T) => string) => T[];
+type ComboboxRootProps<T, Multiple extends boolean = false> = {
+    /** Every item the list can show. With server search, the current results. */
+    items: readonly T[];
+    /**
+     * An item's label: what the input shows once it is picked, and what the default filter
+     * matches. Defaults to the item itself for strings, else its `label` property.
+     */
+    itemToString?: (item: T) => string;
+    /**
+     * An item's identity: how a selected item is recognised when `items` is a fresh array,
+     * and the value the form submits. Defaults to `itemToString`.
+     */
+    itemToKey?: (item: T) => string;
+    /**
+     * Narrows `items` to what matches the input's text. Omitted, a case- and accent-insensitive
+     * "contains" on each label. `null` turns filtering off — `items` are shown as given, which
+     * is what a server search that fills them per query wants.
+     */
+    filter?: ComboboxFilter<T> | null;
+    /** Lets more than one item be selected. `value` is then an array. */
+    multiple?: Multiple;
+    /**
+     * Controlled selection. Provide `onValueChange` alongside it.
+     *
+     * Never `undefined` once mounted: the mode is latched at mount. Use `null` — or `[]` with
+     * `multiple` — for nothing selected.
+     */
+    value?: ComboboxValue$1<T, Multiple>;
+    /** Initial selection when uncontrolled. Read once, at mount. */
+    defaultValue?: ComboboxValue$1<T, Multiple>;
+    onValueChange?: (value: ComboboxValue$1<T, Multiple>, details: ComboboxChangeDetails) => void;
+    /** Controlled text of the input. Provide `onInputValueChange` alongside it. */
+    inputValue?: string;
+    /** Initial text when uncontrolled. Defaults to the selected item's label, without `multiple`. */
+    defaultInputValue?: string;
+    /** Called on every change of the input's text — typing, a pick, Clear, or a close. */
+    onInputValueChange?: (inputValue: string, details: ComboboxChangeDetails) => void;
+    /** Controlled open state. Provide `onOpenChange` alongside it. */
+    open?: boolean;
+    /** Initial open state when uncontrolled. */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean, details: ComboboxChangeDetails) => void;
+    /**
+     * Called when the highlighted item changes, with its index in the filtered list. A
+     * virtualized list scrolls to that index, since the highlighted option must be rendered
+     * for the input's `aria-activedescendant` to reach it.
+     */
+    onItemHighlighted?: (item: T | undefined, details: ComboboxHighlightDetails) => void;
+    /** Called when the end of the list scrolls into view and `loading` is not set. */
+    onLoadMore?: () => void;
+    /** More items are on their way: the list is `aria-busy`, and `Empty` stays hidden. */
+    loading?: boolean;
+    /** Disables the input and every button. */
+    disabled?: boolean;
+    /** Submits each selected item's key under this name, from hidden inputs. */
+    name?: string;
+    /** Associates the hidden inputs with a `<form>` by id, when rendered outside it. */
+    form?: string;
+    children?: ReactNode;
+};
+/**
+ * A text input that filters a list of options, by the WAI-ARIA combobox pattern. Holds the
+ * state and shares it with its parts. Renders no element of its own, apart from the hidden
+ * inputs a form submits.
+ *
+ * Items are data (decision 14): the Root filters `items`, and `Combobox.List` renders what is
+ * left. The selection holds items, not keys, and everything about it — the input's label,
+ * `aria-selected`, the form value — comes from `value`, never from `items` (decision 10). A
+ * selected item stays selected, labelled and submitted after a search stops returning it.
+ *
+ * Focus stays in the input; the highlighted option is its `aria-activedescendant`.
+ */
+declare function ComboboxRoot<T, Multiple extends boolean = false>({ items, itemToString: itemToStringProp, itemToKey: itemToKeyProp, filter, multiple: multipleProp, value: valueProp, defaultValue, onValueChange, inputValue: inputValueProp, defaultInputValue, onInputValueChange, open: openProp, defaultOpen, onOpenChange, onItemHighlighted, onLoadMore, loading, disabled, name, form, children, }: ComboboxRootProps<T, Multiple>): react.JSX.Element;
+
+type ComboboxInputOwnProps = {
+    /** Element to render instead of the default `<input>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxInputProps = ComboboxInputOwnProps & Omit<ComponentPropsWithRef<'input'>, keyof ComboboxInputOwnProps | 'value' | 'defaultValue'>;
+/**
+ * The text input: `role="combobox"`, and the element focus stays on. Its text is the Root's
+ * `inputValue`. It is what the popup is anchored to, unless an InputGroup wraps it.
+ *
+ * Typing opens the list and filters it. Up and Down open it, or move the highlight, wrapping;
+ * Home and End jump to the ends while it is open; Alt+Down opens it without highlighting.
+ * Enter picks the highlighted item; Esc closes. With `multiple`, Backspace in an empty input
+ * removes the last selected item, and Left at the start of the text moves into the chips.
+ *
+ * Leaving the input closes the list and puts the text back: the selected label, or empty
+ * with `multiple`.
+ */
+declare function ComboboxInput({ className, render, ...rest }: ComboboxInputProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxInputGroupOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxInputGroupProps = ComboboxInputGroupOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxInputGroupOwnProps>;
+/**
+ * The field around the Input — chips, Clear and Trigger with it — when they are drawn as one
+ * box. It takes over as the popup's anchor, so the list lines up with the whole field rather
+ * than the text alone, and a press on it is not a press outside.
+ *
+ * A press on the box itself, between its children, focuses the input.
+ */
+declare function ComboboxInputGroup({ className, children, render, ...rest }: ComboboxInputGroupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxTriggerOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxTriggerProps = ComboboxTriggerOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ComboboxTriggerOwnProps>;
+/**
+ * The button that opens and closes the list — usually a chevron. Give it an `aria-label`.
+ *
+ * Out of the tab order and never focused: a press keeps focus in the input, which the
+ * keyboard already opens the list from.
+ */
+declare function ComboboxTrigger({ className, children, render, ...rest }: ComboboxTriggerProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxClearOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxClearProps = ComboboxClearOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ComboboxClearOwnProps>;
+/**
+ * Empties the input and the selection — every selected item, with `multiple`. Give it an
+ * `aria-label`.
+ *
+ * `data-visible` is present while there is a selection to clear; style it hidden otherwise.
+ * Out of the tab order, and a press keeps focus in the input.
+ */
+declare function ComboboxClear({ className, children, render, ...rest }: ComboboxClearProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxSide = AnchorSide;
+type ComboboxAlign = AnchorAlign;
+type ComboboxPopupOwnProps = {
+    /** Which side of the input to open on. Flips to the opposite side when there is no room. */
+    side?: ComboboxSide;
+    /** Where along that side: flush with the input's start or end edge, or centred on it. */
+    align?: ComboboxAlign;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxPopupProps = ComboboxPopupOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxPopupOwnProps | 'popover'>;
+/**
+ * The box the list opens in: a native `popover="manual"` in the top layer, anchored to the
+ * Input as Popover's popup is to its Trigger (decision 12). Holds `List`, and `Empty` and
+ * `Status` if used.
+ *
+ * `manual`, not `auto`: the platform's light dismiss would close the list on a press of the
+ * input itself, and of the Trigger and Clear beside it (decision 14). A press anywhere else
+ * closes it here instead, reported as `'outside-press'`; Esc is the Input's. A press inside
+ * keeps focus in the input.
+ */
+declare function ComboboxPopup({ side, align, className, children, render, ...rest }: ComboboxPopupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxListOwnProps<T> = {
+    /**
+     * A function rendering one `Combobox.Item` per filtered item, or any nodes. With a
+     * virtualizer, render only the rows it asks for.
+     */
+    children?: ReactNode | ((item: T, index: number) => ReactNode);
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxListProps<T = unknown> = ComboboxListOwnProps<T> & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxListOwnProps<T>>;
+/**
+ * The `role="listbox"`. Given a function, renders it once per item the filter left.
+ *
+ * With the Root's `onLoadMore`, an invisible sentinel follows the items; when it scrolls into
+ * view and nothing is `loading`, `onLoadMore` is called. The list is `aria-busy` meanwhile.
+ */
+declare function ComboboxList<T = unknown>({ className, children, render, ...rest }: ComboboxListProps<T>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxItemOwnProps<T> = {
+    /** The item this option stands for — one of the Root's `items`. */
+    value: T;
+    /** Cannot be picked, and the arrow keys skip it. */
+    disabled?: boolean;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxItemProps<T = unknown> = ComboboxItemOwnProps<T> & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxItemOwnProps<T>>;
+/**
+ * One option. A press picks it — with `multiple`, toggles it — and the pointer highlights it.
+ * Never focused: the input keeps focus and points at the highlighted option.
+ *
+ * `data-selected` and `aria-selected` follow the Root's `value`; `data-highlighted` follows
+ * the arrow keys and the pointer. Only the items whose highlight changes re-render.
+ */
+declare function ComboboxItem<T = unknown>({ value, disabled, className, children, render, ...rest }: ComboboxItemProps<T>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxEmptyOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxEmptyProps = ComboboxEmptyOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxEmptyOwnProps>;
+/**
+ * Shown when the filter leaves nothing and nothing is `loading` — "No results". Renders
+ * nothing otherwise. Place it in the Popup, outside the List.
+ */
+declare function ComboboxEmpty({ className, children, render, ...rest }: ComboboxEmptyProps): ReactElement<unknown, string | react.JSXElementConstructor<any>> | null;
+
+type ComboboxStatusOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxStatusProps = ComboboxStatusOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxStatusOwnProps>;
+/**
+ * A polite live region for what a screen reader should hear about the list: "Searching…",
+ * "12 results", an error. Its text is yours; a change to it is announced.
+ */
+declare function ComboboxStatus({ className, children, render, ...rest }: ComboboxStatusProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxChipOwnProps<T> = {
+    /** The selected item this chip shows — one of the Root's `value`. */
+    value: T;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxChipProps<T = unknown> = ComboboxChipOwnProps<T> & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxChipOwnProps<T>>;
+/**
+ * One selected item, with `multiple`. Render one per item of the Root's `value`, before the
+ * Input. Give it an `aria-description` that says how to remove it.
+ *
+ * Out of the tab order. Left from the start of the input reaches the last chip; Left and
+ * Right move between chips, and Right from the last returns to the input; Backspace or
+ * Delete removes the focused chip and moves to the next, or back to the input.
+ */
+declare function ComboboxChip<T = unknown>({ value, className, children, render, ...rest }: ComboboxChipProps<T>): react.JSX.Element;
+
+type ComboboxChipRemoveOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxChipRemoveProps = ComboboxChipRemoveOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ComboboxChipRemoveOwnProps>;
+/**
+ * Removes its Chip's item from the selection. Give it an `aria-label` — "Remove Book".
+ * Out of the tab order; a press returns focus to the input.
+ */
+declare function ComboboxChipRemove({ className, children, render, ...rest }: ComboboxChipRemoveProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxValueProps<T = unknown> = {
+    /**
+     * Renders the selection: `T | null`, or `T[]` with `multiple`. The Root's `itemToString` is
+     * passed along for labels — a chip's text, say.
+     */
+    children: (value: T, details: {
+        itemToString: (item: unknown) => string;
+    }) => ReactNode;
+};
+/**
+ * The current selection, for whatever shows it outside the input — chips, most often. Renders
+ * no element of its own.
+ *
+ * It exists so that a separate styling package can show the selection without owning a copy
+ * of it (decision 9): the value stays the Root's.
+ */
+declare function ComboboxValue<T = unknown>({ children }: ComboboxValueProps<T>): react.JSX.Element;
+
+declare namespace index_parts {
+  export { ComboboxChip as Chip, ComboboxChipRemove as ChipRemove, ComboboxClear as Clear, ComboboxEmpty as Empty, ComboboxInput as Input, ComboboxInputGroup as InputGroup, ComboboxItem as Item, ComboboxList as List, ComboboxPopup as Popup, ComboboxRoot as Root, ComboboxStatus as Status, ComboboxTrigger as Trigger, ComboboxValue as Value };
+}
+
+/**
+ * Combobox's default filter: the items whose label contains the query, ignoring case and
+ * accents, in their original order. An empty query keeps every item.
+ *
+ * Exported so a consumer's own filter can fall back to it, or narrow with it first.
+ */
+declare function defaultFilter<T>(items: readonly T[], query: string, itemToString: (item: T) => string): T[];
+
+export { index_parts as Combobox, type ComboboxAlign, type ComboboxChangeDetails, type ComboboxChangeReason, type ComboboxChipProps, type ComboboxChipRemoveProps, type ComboboxClearProps, type ComboboxEmptyProps, type ComboboxFilter, type ComboboxHighlightDetails, type ComboboxHighlightReason, type ComboboxInputGroupProps, type ComboboxInputProps, type ComboboxItemProps, type ComboboxListProps, type ComboboxPopupProps, type ComboboxRootProps, type ComboboxSide, type ComboboxState, type ComboboxStatusProps, type ComboboxTriggerProps, type ComboboxValue$1 as ComboboxValue, type ComboboxValueProps, defaultFilter };

package/dist/combobox/index.d.ts

@@ -0,0 +1,322 @@
+import * as react from 'react';
+import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
+import { A as AnchorSide, a as AnchorAlign } from '../anchoring-Btxi0QwC.js';
+
+/** Why a value, the input's text or the open state changed — the second callback argument. */
+type ComboboxChangeReason = 'input' | 'input-press' | 'trigger-press' | 'item-press' | 'keyboard' | 'clear' | 'chip-remove' | 'escape' | 'outside-press' | 'blur' | 'form-reset';
+type ComboboxChangeDetails = {
+    reason: ComboboxChangeReason;
+};
+/** Why the highlighted item changed: arrow keys, the pointer, or the component itself. */
+type ComboboxHighlightReason = 'keyboard' | 'pointer' | 'none';
+type ComboboxHighlightDetails = {
+    index: number;
+    reason: ComboboxHighlightReason;
+};
+/** The state Combobox.Root shares with its parts, and projects as `data-*` attributes. */
+type ComboboxState = {
+    open: boolean;
+    multiple: boolean;
+    disabled: boolean;
+};
+
+/** The selection: one item or `null`, or an array with `multiple`. */
+type ComboboxValue$1<T, Multiple extends boolean> = Multiple extends true ? T[] : T | null;
+/** Takes the whole list, so a filter can rank as well as narrow — a fuzzy search, say. */
+type ComboboxFilter<T> = (items: readonly T[], query: string, itemToString: (item: T) => string) => T[];
+type ComboboxRootProps<T, Multiple extends boolean = false> = {
+    /** Every item the list can show. With server search, the current results. */
+    items: readonly T[];
+    /**
+     * An item's label: what the input shows once it is picked, and what the default filter
+     * matches. Defaults to the item itself for strings, else its `label` property.
+     */
+    itemToString?: (item: T) => string;
+    /**
+     * An item's identity: how a selected item is recognised when `items` is a fresh array,
+     * and the value the form submits. Defaults to `itemToString`.
+     */
+    itemToKey?: (item: T) => string;
+    /**
+     * Narrows `items` to what matches the input's text. Omitted, a case- and accent-insensitive
+     * "contains" on each label. `null` turns filtering off — `items` are shown as given, which
+     * is what a server search that fills them per query wants.
+     */
+    filter?: ComboboxFilter<T> | null;
+    /** Lets more than one item be selected. `value` is then an array. */
+    multiple?: Multiple;
+    /**
+     * Controlled selection. Provide `onValueChange` alongside it.
+     *
+     * Never `undefined` once mounted: the mode is latched at mount. Use `null` — or `[]` with
+     * `multiple` — for nothing selected.
+     */
+    value?: ComboboxValue$1<T, Multiple>;
+    /** Initial selection when uncontrolled. Read once, at mount. */
+    defaultValue?: ComboboxValue$1<T, Multiple>;
+    onValueChange?: (value: ComboboxValue$1<T, Multiple>, details: ComboboxChangeDetails) => void;
+    /** Controlled text of the input. Provide `onInputValueChange` alongside it. */
+    inputValue?: string;
+    /** Initial text when uncontrolled. Defaults to the selected item's label, without `multiple`. */
+    defaultInputValue?: string;
+    /** Called on every change of the input's text — typing, a pick, Clear, or a close. */
+    onInputValueChange?: (inputValue: string, details: ComboboxChangeDetails) => void;
+    /** Controlled open state. Provide `onOpenChange` alongside it. */
+    open?: boolean;
+    /** Initial open state when uncontrolled. */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean, details: ComboboxChangeDetails) => void;
+    /**
+     * Called when the highlighted item changes, with its index in the filtered list. A
+     * virtualized list scrolls to that index, since the highlighted option must be rendered
+     * for the input's `aria-activedescendant` to reach it.
+     */
+    onItemHighlighted?: (item: T | undefined, details: ComboboxHighlightDetails) => void;
+    /** Called when the end of the list scrolls into view and `loading` is not set. */
+    onLoadMore?: () => void;
+    /** More items are on their way: the list is `aria-busy`, and `Empty` stays hidden. */
+    loading?: boolean;
+    /** Disables the input and every button. */
+    disabled?: boolean;
+    /** Submits each selected item's key under this name, from hidden inputs. */
+    name?: string;
+    /** Associates the hidden inputs with a `<form>` by id, when rendered outside it. */
+    form?: string;
+    children?: ReactNode;
+};
+/**
+ * A text input that filters a list of options, by the WAI-ARIA combobox pattern. Holds the
+ * state and shares it with its parts. Renders no element of its own, apart from the hidden
+ * inputs a form submits.
+ *
+ * Items are data (decision 14): the Root filters `items`, and `Combobox.List` renders what is
+ * left. The selection holds items, not keys, and everything about it — the input's label,
+ * `aria-selected`, the form value — comes from `value`, never from `items` (decision 10). A
+ * selected item stays selected, labelled and submitted after a search stops returning it.
+ *
+ * Focus stays in the input; the highlighted option is its `aria-activedescendant`.
+ */
+declare function ComboboxRoot<T, Multiple extends boolean = false>({ items, itemToString: itemToStringProp, itemToKey: itemToKeyProp, filter, multiple: multipleProp, value: valueProp, defaultValue, onValueChange, inputValue: inputValueProp, defaultInputValue, onInputValueChange, open: openProp, defaultOpen, onOpenChange, onItemHighlighted, onLoadMore, loading, disabled, name, form, children, }: ComboboxRootProps<T, Multiple>): react.JSX.Element;
+
+type ComboboxInputOwnProps = {
+    /** Element to render instead of the default `<input>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxInputProps = ComboboxInputOwnProps & Omit<ComponentPropsWithRef<'input'>, keyof ComboboxInputOwnProps | 'value' | 'defaultValue'>;
+/**
+ * The text input: `role="combobox"`, and the element focus stays on. Its text is the Root's
+ * `inputValue`. It is what the popup is anchored to, unless an InputGroup wraps it.
+ *
+ * Typing opens the list and filters it. Up and Down open it, or move the highlight, wrapping;
+ * Home and End jump to the ends while it is open; Alt+Down opens it without highlighting.
+ * Enter picks the highlighted item; Esc closes. With `multiple`, Backspace in an empty input
+ * removes the last selected item, and Left at the start of the text moves into the chips.
+ *
+ * Leaving the input closes the list and puts the text back: the selected label, or empty
+ * with `multiple`.
+ */
+declare function ComboboxInput({ className, render, ...rest }: ComboboxInputProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxInputGroupOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxInputGroupProps = ComboboxInputGroupOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxInputGroupOwnProps>;
+/**
+ * The field around the Input — chips, Clear and Trigger with it — when they are drawn as one
+ * box. It takes over as the popup's anchor, so the list lines up with the whole field rather
+ * than the text alone, and a press on it is not a press outside.
+ *
+ * A press on the box itself, between its children, focuses the input.
+ */
+declare function ComboboxInputGroup({ className, children, render, ...rest }: ComboboxInputGroupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxTriggerOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxTriggerProps = ComboboxTriggerOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ComboboxTriggerOwnProps>;
+/**
+ * The button that opens and closes the list — usually a chevron. Give it an `aria-label`.
+ *
+ * Out of the tab order and never focused: a press keeps focus in the input, which the
+ * keyboard already opens the list from.
+ */
+declare function ComboboxTrigger({ className, children, render, ...rest }: ComboboxTriggerProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxClearOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxClearProps = ComboboxClearOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ComboboxClearOwnProps>;
+/**
+ * Empties the input and the selection — every selected item, with `multiple`. Give it an
+ * `aria-label`.
+ *
+ * `data-visible` is present while there is a selection to clear; style it hidden otherwise.
+ * Out of the tab order, and a press keeps focus in the input.
+ */
+declare function ComboboxClear({ className, children, render, ...rest }: ComboboxClearProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxSide = AnchorSide;
+type ComboboxAlign = AnchorAlign;
+type ComboboxPopupOwnProps = {
+    /** Which side of the input to open on. Flips to the opposite side when there is no room. */
+    side?: ComboboxSide;
+    /** Where along that side: flush with the input's start or end edge, or centred on it. */
+    align?: ComboboxAlign;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxPopupProps = ComboboxPopupOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxPopupOwnProps | 'popover'>;
+/**
+ * The box the list opens in: a native `popover="manual"` in the top layer, anchored to the
+ * Input as Popover's popup is to its Trigger (decision 12). Holds `List`, and `Empty` and
+ * `Status` if used.
+ *
+ * `manual`, not `auto`: the platform's light dismiss would close the list on a press of the
+ * input itself, and of the Trigger and Clear beside it (decision 14). A press anywhere else
+ * closes it here instead, reported as `'outside-press'`; Esc is the Input's. A press inside
+ * keeps focus in the input.
+ */
+declare function ComboboxPopup({ side, align, className, children, render, ...rest }: ComboboxPopupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxListOwnProps<T> = {
+    /**
+     * A function rendering one `Combobox.Item` per filtered item, or any nodes. With a
+     * virtualizer, render only the rows it asks for.
+     */
+    children?: ReactNode | ((item: T, index: number) => ReactNode);
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxListProps<T = unknown> = ComboboxListOwnProps<T> & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxListOwnProps<T>>;
+/**
+ * The `role="listbox"`. Given a function, renders it once per item the filter left.
+ *
+ * With the Root's `onLoadMore`, an invisible sentinel follows the items; when it scrolls into
+ * view and nothing is `loading`, `onLoadMore` is called. The list is `aria-busy` meanwhile.
+ */
+declare function ComboboxList<T = unknown>({ className, children, render, ...rest }: ComboboxListProps<T>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxItemOwnProps<T> = {
+    /** The item this option stands for — one of the Root's `items`. */
+    value: T;
+    /** Cannot be picked, and the arrow keys skip it. */
+    disabled?: boolean;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxItemProps<T = unknown> = ComboboxItemOwnProps<T> & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxItemOwnProps<T>>;
+/**
+ * One option. A press picks it — with `multiple`, toggles it — and the pointer highlights it.
+ * Never focused: the input keeps focus and points at the highlighted option.
+ *
+ * `data-selected` and `aria-selected` follow the Root's `value`; `data-highlighted` follows
+ * the arrow keys and the pointer. Only the items whose highlight changes re-render.
+ */
+declare function ComboboxItem<T = unknown>({ value, disabled, className, children, render, ...rest }: ComboboxItemProps<T>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxEmptyOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxEmptyProps = ComboboxEmptyOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxEmptyOwnProps>;
+/**
+ * Shown when the filter leaves nothing and nothing is `loading` — "No results". Renders
+ * nothing otherwise. Place it in the Popup, outside the List.
+ */
+declare function ComboboxEmpty({ className, children, render, ...rest }: ComboboxEmptyProps): ReactElement<unknown, string | react.JSXElementConstructor<any>> | null;
+
+type ComboboxStatusOwnProps = {
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxStatusProps = ComboboxStatusOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxStatusOwnProps>;
+/**
+ * A polite live region for what a screen reader should hear about the list: "Searching…",
+ * "12 results", an error. Its text is yours; a change to it is announced.
+ */
+declare function ComboboxStatus({ className, children, render, ...rest }: ComboboxStatusProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxChipOwnProps<T> = {
+    /** The selected item this chip shows — one of the Root's `value`. */
+    value: T;
+    /** Element to render instead of the default `<div>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxChipProps<T = unknown> = ComboboxChipOwnProps<T> & Omit<ComponentPropsWithRef<'div'>, keyof ComboboxChipOwnProps<T>>;
+/**
+ * One selected item, with `multiple`. Render one per item of the Root's `value`, before the
+ * Input. Give it an `aria-description` that says how to remove it.
+ *
+ * Out of the tab order. Left from the start of the input reaches the last chip; Left and
+ * Right move between chips, and Right from the last returns to the input; Backspace or
+ * Delete removes the focused chip and moves to the next, or back to the input.
+ */
+declare function ComboboxChip<T = unknown>({ value, className, children, render, ...rest }: ComboboxChipProps<T>): react.JSX.Element;
+
+type ComboboxChipRemoveOwnProps = {
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type ComboboxChipRemoveProps = ComboboxChipRemoveOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof ComboboxChipRemoveOwnProps>;
+/**
+ * Removes its Chip's item from the selection. Give it an `aria-label` — "Remove Book".
+ * Out of the tab order; a press returns focus to the input.
+ */
+declare function ComboboxChipRemove({ className, children, render, ...rest }: ComboboxChipRemoveProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type ComboboxValueProps<T = unknown> = {
+    /**
+     * Renders the selection: `T | null`, or `T[]` with `multiple`. The Root's `itemToString` is
+     * passed along for labels — a chip's text, say.
+     */
+    children: (value: T, details: {
+        itemToString: (item: unknown) => string;
+    }) => ReactNode;
+};
+/**
+ * The current selection, for whatever shows it outside the input — chips, most often. Renders
+ * no element of its own.
+ *
+ * It exists so that a separate styling package can show the selection without owning a copy
+ * of it (decision 9): the value stays the Root's.
+ */
+declare function ComboboxValue<T = unknown>({ children }: ComboboxValueProps<T>): react.JSX.Element;
+
+declare namespace index_parts {
+  export { ComboboxChip as Chip, ComboboxChipRemove as ChipRemove, ComboboxClear as Clear, ComboboxEmpty as Empty, ComboboxInput as Input, ComboboxInputGroup as InputGroup, ComboboxItem as Item, ComboboxList as List, ComboboxPopup as Popup, ComboboxRoot as Root, ComboboxStatus as Status, ComboboxTrigger as Trigger, ComboboxValue as Value };
+}
+
+/**
+ * Combobox's default filter: the items whose label contains the query, ignoring case and
+ * accents, in their original order. An empty query keeps every item.
+ *
+ * Exported so a consumer's own filter can fall back to it, or narrow with it first.
+ */
+declare function defaultFilter<T>(items: readonly T[], query: string, itemToString: (item: T) => string): T[];
+
+export { index_parts as Combobox, type ComboboxAlign, type ComboboxChangeDetails, type ComboboxChangeReason, type ComboboxChipProps, type ComboboxChipRemoveProps, type ComboboxClearProps, type ComboboxEmptyProps, type ComboboxFilter, type ComboboxHighlightDetails, type ComboboxHighlightReason, type ComboboxInputGroupProps, type ComboboxInputProps, type ComboboxItemProps, type ComboboxListProps, type ComboboxPopupProps, type ComboboxRootProps, type ComboboxSide, type ComboboxState, type ComboboxStatusProps, type ComboboxTriggerProps, type ComboboxValue$1 as ComboboxValue, type ComboboxValueProps, defaultFilter };