svelte-5-select 1.0.0 → 2.0.0

package/dist/types.d.ts

@@ -1,205 +1,535 @@
 import type { Snippet } from 'svelte';
+import type { HTMLInputAttributes } from 'svelte/elements';
 import type { ComputePositionConfig } from 'svelte-floating-ui/dom';
-export type SelectValue = SelectItem | SelectItem[] | null;
-export interface ErrorEvent {
-    type: string;
+/**
+ * The bound for user item types. Deliberately `Record<string, any>` rather than
+ * {@link SelectItem}: interface-declared item types have no implicit index
+ * signature, so they satisfy this bound but not `SelectItem` itself.
+ */
+export type ItemLike = Record<string, any>;
+/**
+ * The payload shape of `onValueChange`/`onSelectionChange`: an item array in
+ * multiple mode, a single item or null otherwise. `Multiple` defaults to
+ * `boolean`, which distributes to the loose `Item[] | Item | null` union.
+ */
+export type SelectValue<Item extends ItemLike = SelectItem, Multiple extends boolean = boolean> = Multiple extends true ? Item[] : Item | null;
+/**
+ * The bindable `value` prop shape: raw string ids are also accepted and are
+ * normalized into items against `items`.
+ *
+ * The component always *writes* `undefined` for an empty selection — in both single
+ * and multiple mode, and on every clear path (the clear button, removing the last
+ * tag, a `loadOptionsDeps` reload invalidating the value, a multiple→single switch).
+ * `null` is accepted on the way in, so an existing `bind:value` initialized to `null`
+ * keeps working; read an emptied value as falsy rather than testing `=== null`.
+ * (The `onValueChange`/`onSelectionChange` payload is a separate contract — see
+ * {@link SelectValue} — and reports `null` in single mode and `[]` in multiple mode.)
+ */
+export type SelectValueProp<Item extends ItemLike = SelectItem, Multiple extends boolean = boolean> = Multiple extends true ? Item[] | string[] | null | undefined : Item | string | null | undefined;
+/**
+ * The payload of `onclear`. Clearing the whole selection passes the full removed
+ * value (an `Item[]` in multiple mode); removing a single tag in multiple mode
+ * passes just that removed entry. Discriminated by `Multiple` so single mode never
+ * has to account for an array, and one-tag removal is only in the multiple branch.
+ * Raw string ids are included because `value` accepts them.
+ */
+export type SelectClearValue<Item extends ItemLike = SelectItem, Multiple extends boolean = boolean> = Multiple extends true ? Item[] | string[] | Item | string | null : Item | string | null;
+/** Payload of the `onerror` callback. `type` discriminates the failure source; `loadOptions` (a rejected loader promise) is currently the only emitter, with the rejection reason in `details`. */
+export interface SelectErrorEvent {
+    type: 'loadOptions';
     details: unknown;
 }
-export interface FilterConfig {
-    loadOptions?: (filterText: string) => Promise<SelectItem[] | string[]>;
+/** The configuration object a custom `filter` prop receives — a snapshot of everything the built-in pipeline uses. See the exported `filter` for the default implementation to delegate to or replace. */
+export interface FilterConfig<Item extends ItemLike = SelectItem> {
+    /** The `loadOptions` prop, if set. When present, results are already filtered remotely — the default pipeline skips `itemFilter` entirely. */
+    loadOptions?: (filterText: string) => Promise<Item[] | string[]>;
+    /** The current filter text. */
     filterText: string;
-    items: SelectItem[] | string[] | null;
+    /** The `items` prop as supplied — entries may still be raw strings; pass them through `convertStringItemsToObjects` before reading item fields. */
+    items: Item[] | string[] | null;
+    /** The `multiple` prop. */
     multiple: boolean;
-    value: SelectItem | SelectItem[] | null | undefined;
+    /** The current (normalized) selection; raw string entries have already been synthesized into `SelectItem`s. Used with `filterSelectedItems` to hide picked options. */
+    value: Item | SelectItem | (Item | SelectItem)[] | null | undefined;
+    /** The `itemId` prop — the field name selections are compared by. */
     itemId: string;
-    groupBy?: (item: SelectItem) => string | undefined;
+    /** The `groupBy` prop, if set. */
+    groupBy?: (item: Item) => string;
+    /** The `label` prop — the field name option text is read from. */
     label: string;
+    /** The `filterSelectedItems` prop: hide already-selected options in multiple mode. */
     filterSelectedItems: boolean;
-    itemFilter: (label: string, filterText: string, option: SelectItem) => boolean;
+    /** The per-item match predicate (the `itemFilter` prop). The default pipeline skips it when `loadOptions` is set. */
+    itemFilter: (label: string, filterText: string, option: Item) => boolean;
+    /** Synthesizes `{ value, label, index }` items from raw string entries. */
     convertStringItemsToObjects: (items: string[]) => SelectItem[];
-    filterGroupedItems: (items: SelectItem[]) => SelectItem[];
+    /**
+     * Transforms the flat filtered list into a grouped one (inserting headers and
+     * applying the `groupBy`/`groupFilter` props). Distinct from the `groupFilter`
+     * prop, which only reorders/filters the group keys this transform consumes.
+     */
+    applyGrouping: (items: SelectItem[]) => SelectItem[];
 }
+/** The `floatingConfig` prop shape: floating-ui's `computePosition` options plus `autoUpdate` to reposition on scroll/resize. */
 export interface FloatingConfig extends Partial<ComputePositionConfig> {
     autoUpdate?: boolean;
 }
-export interface KeyboardNavigationContext {
-    getState: () => {
-        listOpen: boolean;
-        filteredItems: SelectItem[];
-        hoverItemIndex: number;
-        multiple: boolean;
-        value: SelectProps['value'];
-        filterText: string;
-        activeValue: number | undefined;
-        itemId: string;
-        focused: boolean;
-    };
-    setListOpen: (value: boolean) => void;
-    setHoverItemIndex: (value: number) => void;
-    setActiveValue: (value: number | undefined) => void;
+/**
+ * The `justValue` shape: bare `itemId` values instead of whole items. Includes
+ * `undefined` because that is what the component writes for an emptied selection —
+ * on every clear path, mirroring `value` (see {@link SelectValueProp}). `null` and
+ * `[]` are accepted on the way in but never written back.
+ */
+export type JustValue = string | number | string[] | number[] | null | undefined;
+/** The default item shape (and the shape synthesized for raw string items). Your own item type does not need to extend it — any {@link ItemLike} works; these are just the fields the component reads when present. */
+export interface SelectItem {
+    value?: unknown;
+    label?: string;
+    index?: number;
+    group?: string;
+    groupHeader?: boolean;
+    groupItem?: boolean;
+    selectable?: boolean;
+    id?: string | number;
+    [key: string]: unknown;
+}
+/**
+ * A group header row synthesized by `groupBy` and injected into the rendered list.
+ * It is not one of your items — it carries the group's own value and label plus the
+ * marker fields, and nothing else — so it cannot be read as an `Item`.
+ */
+export interface SelectGroupHeader extends SelectItem {
+    groupHeader: true;
+    selectable: boolean;
+}
+/**
+ * A row of the rendered list. With `groupBy` set the list interleaves your items with
+ * synthesized {@link SelectGroupHeader} rows, so everything that reads the rendered
+ * list — `getFilteredItems()`, `onfilter`, `listSnippet`, `itemSnippet` — sees this
+ * union rather than a bare `Item`. Narrow it with {@link isGroupHeader}:
+ *
+ * ```svelte
+ * {#snippet itemSnippet(row)}
+ *     {#if isGroupHeader(row)}
+ *         <strong>{row.label}</strong>
+ *     {:else}
+ *         {row.name} <!-- row is your Item here -->
+ *     {/if}
+ * {/snippet}
+ * ```
+ *
+ * Without `groupBy` no headers are ever produced, but the type cannot know that
+ * statically — the guard is a one-line narrow in that case.
+ */
+export type SelectRow<Item extends ItemLike = SelectItem> = Item | SelectGroupHeader;
+/**
+ * The single reactive state object shared by Select.svelte and its composables.
+ * Prop-backed fields are live accessors over the component's `$props()` bindings;
+ * the rest is internal shared state owned by `createSelectState`. Reading a field
+ * tracks only that field's signal.
+ */
+export interface SelectState<Item extends ItemLike = SelectItem> {
+    value: Item | Item[] | string | string[] | null | undefined;
+    items: Item[] | string[] | null;
+    filterText: string;
+    justValue: JustValue;
+    listOpen: boolean;
+    loading: boolean;
+    focused: boolean;
+    hoverItemIndex: number;
+    readonly multiple: boolean;
+    readonly itemId: string;
+    readonly label: string;
+    readonly searchable: boolean;
+    readonly disabled: boolean;
+    readonly useJustValue: boolean;
+    readonly closeListOnChange: boolean;
+    readonly debounceWait: number;
+    readonly groupBy: ((item: Item) => string) | undefined;
+    readonly loadOptions: ((filterText: string) => Promise<Item[] | string[]>) | undefined;
+    readonly loadOptionsDeps: unknown[];
+    readonly filteredItems: SelectItem[];
+    readonly normalizedValue: SelectItem | SelectItem[] | null;
+    readonly hasValue: boolean;
+    activeValue: number | undefined;
+    isScrolling: boolean;
+    clearState: boolean;
+    prevValue: Item | Item[] | string | string[] | null | undefined;
+    prevFilterText: string | undefined;
+    prevMultiple: boolean | undefined;
+    /**
+     * One-shot handshake between type-ahead and the hover effects: set when a
+     * type-ahead keypress opens the list *and* parks hover on its match, so the
+     * open-with-value effect must not snap hover back to the selected value.
+     * Consumed (cleared) on the next run of that effect. Deliberately
+     * non-reactive scratch, like the prev* fields.
+     */
+    suppressValueHoverSnap: boolean;
+    /**
+     * Whether the user has expressed commit-intent since the list last opened:
+     * moved the option cursor (arrow/Home/End/Page keys, type-ahead), typed in
+     * the input, or moved the pointer over the open list (mousemove, not
+     * mouseover — browsers synthesize mouseover for content appearing under a
+     * stationary cursor). Tab only commits the hovered option when this is set —
+     * the cursor auto-parks on an option the moment the list opens, and a bare
+     * open-then-Tab must close without selecting. Reset whenever the list
+     * closes. Deliberately non-reactive scratch, like the prev* fields.
+     */
+    userNavigatedSinceOpen: boolean;
+}
+/** The subset of {@link SelectState} that keyboard navigation needs; any object with these fields works. */
+export interface KeyboardNavigationState<Item extends ItemLike = SelectItem> {
+    listOpen: boolean;
+    readonly filteredItems: SelectItem[];
+    hoverItemIndex: number;
+    readonly multiple: boolean;
+    readonly value: Item | Item[] | string | string[] | null | undefined;
+    readonly filterText: string;
+    activeValue: number | undefined;
+    readonly itemId: string;
+    readonly label: string;
+    readonly searchable: boolean;
+    readonly focused: boolean;
+    readonly disabled: boolean;
+    /** See {@link SelectState.suppressValueHoverSnap} — written by type-ahead when it opens the list. */
+    suppressValueHoverSnap: boolean;
+    /** See {@link SelectState.userNavigatedSinceOpen} — gates Tab's commit-on-close. */
+    userNavigatedSinceOpen: boolean;
+}
+export interface KeyboardNavigationActions {
     closeList: () => void;
     setHoverIndex: (increment: number) => void;
     handleSelect: (item: SelectItem) => void;
-    handleMultiItemClear: (index: number) => Promise<void>;
+    handleMultiItemClear: (index: number) => void | Promise<void>;
 }
-export interface HoverContext {
-    getState: () => {
-        listOpen: boolean;
-        filteredItems: SelectItem[];
-        hoverItemIndex: number;
-        multiple: boolean;
-        value: SelectProps['value'];
-        isScrolling: boolean;
-        groupBy: ((item: SelectItem) => string) | undefined;
-        itemId: string;
-    };
-    setHoverItemIndex: (value: number) => void;
-    setIsScrolling: (value: boolean) => void;
-    onhoveritem: (index: number) => void;
-}
-export type JustValue = string | number | string[] | number[] | null;
-export interface ValueContext {
-    getState: () => {
-        value: SelectProps['value'];
-        prevValue: SelectProps['value'];
-        items: SelectItem[] | string[] | null;
-        multiple: boolean;
-        itemId: string;
-        label: string;
-        hasValue: boolean;
-        normalizedValue: SelectItem | SelectItem[] | null;
-        useJustValue: boolean;
-        justValue: JustValue | undefined;
-        clearState: boolean;
-        closeListOnChange: boolean;
-    };
-    setValue: (value: SelectProps['value']) => void;
-    setJustValue: (value: JustValue) => void;
-    setPrevValue: (value: SelectProps['value']) => void;
-    setClearState: (value: boolean) => void;
-    setActiveValue: (value: number | undefined) => void;
-    setFilterText: (value: string) => void;
+export interface ValueActions {
     closeList: () => void;
-    oninput: (value: SelectProps['value']) => void;
-    onchange: (value: SelectProps['value']) => void;
-    onclear: (value: SelectProps['value'] | SelectItem) => void;
+    /**
+     * Retire a pending dependency-reload's validation verdict when the selection
+     * being committed was picked from fresher results (see useLoadOptions).
+     * Optional: standalone useValue has no async loading to retire.
+     */
+    retireStaleValidation?: () => void;
+    onValueChange: (value: SelectItem | string | (SelectItem | string)[] | null | undefined) => void;
+    onSelectionChange: (value: SelectItem | string | (SelectItem | string)[] | null | undefined) => void;
+    onclear: (value: SelectItem | string | (SelectItem | string)[] | null | undefined) => void;
     onselect: (selection: SelectItem) => void;
 }
-export interface LoadOptionsContext {
-    getState: () => {
-        filterText: string;
-        prevFilterText: string | undefined;
-        loadOptionsDeps: any[];
-        loadOptions: ((filterText: string) => Promise<SelectItem[] | string[]>) | undefined;
-        disabled: boolean;
-        multiple: boolean;
-        value: SelectProps['value'];
-        items: SelectItem[] | string[] | null;
-        itemId: string;
-        useJustValue: boolean;
-        justValue: JustValue | undefined;
-        listOpen: boolean;
-        debounceWait: number;
-    };
-    setItems: (items: SelectItem[] | string[] | null) => void;
-    setValue: (value: SelectProps['value']) => void;
-    setJustValue: (value: JustValue) => void;
-    setLoading: (value: boolean) => void;
-    setListOpen: (value: boolean) => void;
+export interface LoadOptionsActions {
     debounce: (fn: () => void, wait: number) => void;
-    convertStringItemsToObjects: (items: string[]) => SelectItem[];
     onloaded: (options: SelectItem[]) => void;
-    onerror: (error: ErrorEvent) => void;
-}
-export interface ScrollActionParams {
-    scroll: boolean;
-}
-export interface SelectItem {
-    value?: any;
-    label?: string;
-    index?: number;
-    group?: string;
-    groupHeader?: boolean;
-    groupItem?: boolean;
-    selectable?: boolean;
-    id?: string | number;
-    [key: string]: any;
+    onerror: (error: SelectErrorEvent) => void;
 }
-export interface SelectProps {
+/**
+ * Props of the `<Select>` component.
+ *
+ * The surface is deliberately closed: unknown attributes are not spread onto the
+ * container element. Style via `class`/`containerStyles`, reach the input element
+ * via `inputAttributes`/`id`, and wrap the component when the container itself
+ * needs extra attributes (e.g. `data-testid`). Keeping it closed means a later
+ * release can add passthrough without a breaking change — the reverse is not true.
+ */
+export interface SelectProps<Item extends ItemLike = SelectItem, Multiple extends boolean = false> {
+    /**
+     * Bindable. The text typed into the input; drives filtering and `loadOptions`.
+     * An initial value is kept on mount and applied passively: it filters (and
+     * fetches, with `loadOptions`) but does not open the list or move focus.
+     * Later programmatic writes behave like typing and open the list.
+     *
+     * The DOM input's value is only ever this filter text — a selection is
+     * rendered alongside the input (and announced via the live regions), never
+     * written into the textbox. Read the selection from `value`/`justValue` or
+     * the form field (`name`), not from the DOM input.
+     */
     filterText?: string;
+    /** Which field uniquely identifies an item. Values are compared by this field, not by reference. @default 'value' */
     itemId?: string;
-    items?: SelectItem[] | string[] | null;
+    /**
+     * Bindable. The options to choose from. A `string[]` is converted to
+     * `{ value, label, index }` items for you. Leave unset when using `loadOptions`,
+     * which populates this.
+     */
+    items?: Item[] | string[] | null;
+    /**
+     * Bindable, and only meaningful with `useJustValue`: the selection reduced to bare
+     * `itemId` values (`'a'` / `['a', 'b']`) instead of whole items. Writing it while
+     * no selection exists hydrates `value` — the matching items are resolved out of
+     * `items`, retrying when async items arrive. While a selection exists, `justValue`
+     * is derived from it and a conflicting write is corrected back: write (or clear)
+     * `value` to change the selection.
+     *
+     * Empty is always `undefined`: every clear path writes `undefined`, never `''`,
+     * `null`, or `[]` — read an emptied `justValue` as falsy rather than `=== null`.
+     */
     justValue?: JustValue;
+    /** Which field holds an item's display text. @default 'label' */
     label?: string;
-    value?: SelectItem | SelectItem[] | string | null;
+    /**
+     * Bindable. The current selection: an item (or `Item[]` with `multiple`), or a raw
+     * string id that is normalized against `items`. Empty is always `undefined` —
+     * see {@link SelectValueProp}.
+     */
+    value?: SelectValueProp<Item, Multiple>;
+    /**
+     * Blocks interaction: the list closes, focus is released, and typing and
+     * keyboard navigation are ignored. The selection is kept — except with
+     * `loadOptions`, where disabling clears `value` and `items` (loaded options
+     * may be stale by re-enable). Rendered as `aria-disabled` + `readonly`
+     * rather than the native `disabled` attribute, so the current value stays
+     * in the accessibility tree.
+     */
     disabled?: boolean;
+    /**
+     * Bindable. Whether the input has focus. Writable: setting `true` moves DOM
+     * focus to the input, `false` blurs it and closes the list.
+     */
     focused?: boolean;
+    /** Applies the error styling and sets `aria-invalid`. Pair with `ariaErrorMessage`. */
     hasError?: boolean;
+    /** Renders nothing instead of the "No options" row when the list is empty. Also suppresses a supplied `emptySnippet`. */
     hideEmptyState?: boolean;
+    /** The input's `id`, for an external `<label for>`. Also seeds every internal id; one is generated if unset. */
     id?: string | null;
+    /** Bindable. Whether the option list is open. */
     listOpen?: boolean;
+    /** Bindable. Shows the spinner and sets `aria-busy`. Managed for you while `loadOptions` is in flight. */
     loading?: boolean;
+    /** Name of the hidden input, for native form submission. */
     name?: string | null;
+    /** Prompt shown in the empty input; also the input's last-resort accessible name (see `ariaLabel`). @default 'Please select' */
     placeholder?: string;
+    /** Keep the placeholder visible even when an item is selected (multiple mode). */
     placeholderAlwaysShow?: boolean;
+    /** Show the chevron indicator on the right of the control. @default false */
     showChevron?: boolean;
+    /** Show the clear-all button. @default true */
     clearable?: boolean;
+    /** Reset `filterText` when the input loses focus. @default true */
     clearFilterTextOnBlur?: boolean;
+    /** Close the list after a selection. Set `false` to keep picking in multiple mode. @default true */
     closeListOnChange?: boolean;
+    /** Hide already-selected items from the list. @default true */
     filterSelectedItems?: boolean;
+    /**
+     * Let group headers be selected like options; otherwise they are presentational.
+     *
+     * A selected header is the synthesized {@link SelectGroupHeader} row, not one of
+     * your items — but `value` and the `onselect`/`onSelectionChange`/`onValueChange`
+     * payloads deliberately keep their ergonomic `Item` typing rather than forcing
+     * every consumer through a union. If you enable this, narrow those payloads with
+     * `isGroupHeader` before reading item fields off them.
+     */
     groupHeaderSelectable?: boolean;
+    /** Clicking anywhere on a tag removes it, and the whole tag becomes a keyboard tab stop. */
     multiFullItemClearable?: boolean;
-    multiple?: boolean;
+    /**
+     * Allow several selections, rendered as tags. Drives typing: with `multiple`,
+     * `value` and the `onValueChange`/`onSelectionChange` payloads narrow to `Item[]`.
+     */
+    multiple?: Multiple;
+    /** Block native form submission while nothing is selected, and set `aria-required`. */
     required?: boolean;
+    /** Allow typing to filter. When `false` the input is read-only and printable keys jump to matching options. @default true */
     searchable?: boolean;
+    /** Mirror the selection into `justValue` as bare ids, and hydrate `value` from it on mount. */
     useJustValue?: boolean;
+    /** Extra class(es) on the container, alongside `svelte-select`. */
     class?: string;
+    /** Inline styles on the container. */
     containerStyles?: string;
+    /** Inline styles on the text input. */
     inputStyles?: string;
-    listStyle?: string;
+    /** Inline styles on the option list. */
+    listStyles?: string;
+    /** How long typing settles before `loadOptions` fires, in ms. Only typing is debounced. @default 300 */
     debounceWait?: number;
+    /** Passed to floating-ui to position the list (placement, middleware, autoUpdate). */
     floatingConfig?: FloatingConfig;
+    /** Bindable. Index of the option under the keyboard cursor. */
     hoverItemIndex?: number;
-    inputAttributes?: Record<string, any>;
+    /**
+     * Extra attributes for the text input. Merged over the component's own ARIA
+     * wiring, so it can override it. Event handlers are the exception: an
+     * `oninput`/`onblur`/`onfocus`/`onkeydown` here composes with (runs after)
+     * the component's own handler instead of replacing it, so filtering, focus
+     * handling, and keyboard navigation keep working alongside yours.
+     */
+    inputAttributes?: HTMLInputAttributes;
+    /** Size the list to the container's width. @default true */
     listAutoWidth?: boolean;
+    /** Gap between the container and the list, in px. @default 5 */
     listOffset?: number;
-    loadOptionsDeps?: any[];
-    createGroupHeaderItem?: (groupValue: string, item: SelectItem) => SelectItem;
+    /**
+     * Values that `loadOptions` depends on (e.g. a parent select's value). When any of
+     * them changes, options are re-fetched immediately (no debounce) and the current
+     * selection is validated against the result: entries a non-empty result no longer
+     * offers are dropped (the whole value clears to `undefined` only when nothing
+     * survives). An empty result is treated as no evidence and never clears — a search
+     * endpoint returns nothing for the retained (usually empty) filter text regardless
+     * of the selection. Typing-driven loads never invalidate the selection this way.
+     *
+     * Elements are compared by identity (`===`): pass primitives (`[country.id]`) or
+     * stable references, not inline literals (`[{ country }]` recreates the object per
+     * parent render and re-fires the reload every time — a dev-only warning surfaces
+     * this).
+     */
+    loadOptionsDeps?: unknown[];
+    /** Builds the header row for a group; receives the group's value and its first item. */
+    createGroupHeaderItem?: (groupValue: string, item: NoInfer<Item>) => SelectItem;
+    /** Replace the debounce strategy used for typing-driven `loadOptions` calls. */
     debounce?: (fn: () => void, wait: number) => void;
-    filter?: (config: FilterConfig) => SelectItem[];
-    getFilteredItems?: () => SelectItem[];
-    groupBy?: ((item: SelectItem) => string) | undefined;
+    /**
+     * Replace the whole filtering pipeline. Most cases only need `itemFilter`.
+     * May return your own `Item`s directly, rows from `config.applyGrouping` /
+     * `config.convertStringItemsToObjects`, or a mix.
+     */
+    filter?: (config: FilterConfig<NoInfer<Item>>) => (Item | SelectItem)[];
+    /**
+     * Returns the group an item belongs to. Setting this makes the list interleave
+     * synthesized header rows with your items — see {@link SelectRow}.
+     */
+    groupBy?: ((item: NoInfer<Item>) => string) | undefined;
+    /** Reorders or filters the group keys produced by `groupBy`. */
     groupFilter?: (groups: string[]) => string[];
-    itemFilter?: (label: string, filterText: string, option: SelectItem) => boolean;
-    loadOptions?: (filterText: string) => Promise<SelectItem[] | string[]>;
+    /** Decides whether one option survives the current `filterText`. Not applied to `loadOptions` results. */
+    itemFilter?: (label: string, filterText: string, option: NoInfer<Item>) => boolean;
+    /**
+     * Fetches options asynchronously. Runs on mount, on typing (debounced by
+     * `debounceWait`), and whenever `loadOptionsDeps` or `disabled` changes.
+     * Opening or closing the list never fetches, with one exception: reopening
+     * with retained filter text whose load was cancelled on close (e.g. with
+     * `clearFilterTextOnBlur={false}`) refreshes the stale results immediately.
+     * Whatever it returns is what the list shows: results are not re-filtered by
+     * `filterText`. Set `items` or this, not both.
+     */
+    loadOptions?: (filterText: string) => Promise<Item[] | string[]>;
+    /** Announced when the selection is cleared. */
+    ariaCleared?: () => string;
+    /** `aria-label` for the clear-all button. */
+    ariaClearSelectLabel?: string;
+    /** Announced when an open list has no results. Also rendered as the list's visible empty-state copy (unless `emptySnippet` replaces it), so overriding it localizes both. */
+    ariaEmpty?: () => string;
+    /** id of an external element describing the error; wired to `aria-errormessage` only while `hasError` is true. */
+    ariaErrorMessage?: string;
+    /** Announced when the input is focused with the list closed. The default omits its "type to refine list" phrase when `searchable` is `false`. */
     ariaFocused?: () => string;
+    /**
+     * Accessible name for the input. Prefer an external `<label for={id}>`; this
+     * overrides it. With neither, the placeholder is a last-resort fallback that some
+     * screen readers ignore, and a dev-only warning fires.
+     */
     ariaLabel?: string;
+    /**
+     * Announced when the list opens and when filtering changes the result count — not
+     * on every arrow key, since `aria-activedescendant` already announces each option
+     * as the cursor reaches it. Receives the focused option's label and the count.
+     */
     ariaListOpen?: (label: string, count: number) => string;
+    /** Announced while an open list is still fetching options. Also rendered as the list's visible loading copy (unless `emptySnippet` replaces it), so overriding it localizes both. */
+    ariaLoading?: () => string;
+    /** `aria-label` for each multi-select tag's remove button; receives the item's label. */
+    ariaRemoveItemLabel?: (label: string) => string;
+    /** Announced when the selection changes; receives the selected labels, comma-joined. */
     ariaValues?: (values: string) => string;
-    handleClear?: () => void;
+    /**
+     * Replaces the clear button's behavior entirely — the default clear (emptying
+     * `value`, firing `onclear`, closing the list, refocusing the input) does not run,
+     * so an override owns all of it. To merely observe a clear, use `onclear`.
+     */
+    handleClear?: (e?: MouseEvent) => void;
+    /** Literal DOM `blur` passthrough from the text input. Fires after the component's own blur handling (list close, filter-text reset). */
     onblur?: (e: FocusEvent) => void;
-    onchange?: (value: SelectValue) => void;
-    onclear?: (value: SelectValue) => void;
-    onerror?: (error: ErrorEvent) => void;
-    onfilter?: (items: SelectItem[]) => void;
+    /** Clear-all receives the full removed value; removing one tag receives that single entry. */
+    onclear?: (value: SelectClearValue<Item, Multiple>) => void;
+    /** Fires when a `loadOptions` promise rejects. */
+    onerror?: (error: SelectErrorEvent) => void;
+    /**
+     * Fires with the rendered list whenever it changes while open. Rows include any
+     * synthesized group headers — narrow with `isGroupHeader`.
+     */
+    onfilter?: (items: SelectRow<Item>[]) => void;
+    /** Literal DOM `focus` passthrough from the text input. Fires after the component's own focus handling. */
     onfocus?: (e: FocusEvent) => void;
+    /** Fires with the index of the option under the keyboard/mouse cursor. */
     onhoveritem?: (index: number) => void;
-    oninput?: (value: SelectValue) => void;
-    onloaded?: (options: SelectItem[]) => void;
-    onselect?: (selection: SelectItem) => void;
+    /**
+     * Fires with the options a `loadOptions` call resolved. When the loader
+     * resolves raw strings, the delivered options are the synthesized
+     * `{ value, label, index }` items built from them — `SelectItem`s, not your
+     * item type — hence the widened element type. An item-resolving loader only
+     * ever delivers `Item`s.
+     */
+    onloaded?: (options: (Item | SelectItem)[]) => void;
+    /**
+     * Fires alongside {@link SelectProps.onSelectionChange} when the user picks an
+     * option, but receives just the item selected rather than the whole value.
+     */
+    onselect?: (selection: Item) => void;
+    /**
+     * Fires only when the user picks an option from the list — never on a clear, a
+     * programmatic `bind:value` write, or a `loadOptionsDeps` invalidation. Use
+     * {@link SelectProps.onValueChange} to observe every value change instead.
+     * (Renamed from `onchange` in v2: it is a component state-change callback, not
+     * the DOM `change` event.)
+     */
+    onSelectionChange?: (value: SelectValue<Item, Multiple>) => void;
+    /**
+     * Fires on *every* value change — a user selection, a clear, a programmatic
+     * `bind:value` write, or a `loadOptionsDeps` invalidation. Contrast
+     * {@link SelectProps.onSelectionChange}, which only fires for a user selection.
+     * An emptied value arrives here as `null` (single) or `[]` (multiple), which is
+     * the one place those shapes appear — `bind:value` itself always empties to
+     * `undefined`. (Renamed from `oninput` in v2: typing is `bind:filterText`, and
+     * an `oninput` that never fired per keystroke read as the DOM event it wasn't.)
+     */
+    onValueChange?: (value: SelectValue<Item, Multiple>) => void;
+    /** Replaces the chevron icon; the boolean is `listOpen`, so the icon can flip while open. Rendered only with `showChevron`. */
     chevronIconSnippet?: Snippet<[boolean]>;
+    /** Replaces the icon inside the clear-all button (the button itself, its `ariaClearSelectLabel`, and its behavior stay). */
     clearIconSnippet?: Snippet;
+    /** Replaces the "No options" row of an open, empty list. Suppressed entirely by `hideEmptyState`. */
     emptySnippet?: Snippet;
-    inputHiddenSnippet?: Snippet<[SelectValue]>;
-    itemSnippet?: Snippet<[SelectItem, number]>;
+    /**
+     * Replaces the hidden input(s) used for native form submission; receives the
+     * current value. Overriding takes charge of serialization — render your own
+     * `<input type="hidden" name={...}>` (the default submits JSON-stringified
+     * items, or bare ids with `useJustValue`).
+     */
+    inputHiddenSnippet?: Snippet<[SelectValueProp<Item, Multiple> | undefined]>;
+    /**
+     * Renders one row of the list. Also renders synthesized group headers when
+     * `groupBy` is set — narrow with `isGroupHeader`.
+     */
+    itemSnippet?: Snippet<[SelectRow<Item>, number]>;
+    /** Rendered inside the list after the options — e.g. a "load more" row or footer. */
     listAppendSnippet?: Snippet;
+    /** Rendered inside the list before the options — e.g. a sticky header. */
     listPrependSnippet?: Snippet;
-    listSnippet?: Snippet<[SelectItem[]]>;
+    /**
+     * Replaces the entire list body. Rows include any synthesized group headers —
+     * narrow with `isGroupHeader`.
+     *
+     * Note: taking over rendering means `aria-activedescendant` can no longer resolve
+     * to an option, so give each rendered option `id="listbox-{id}-item-{index}"` and
+     * `role="option"` to keep the combobox navigable by screen readers.
+     */
+    listSnippet?: Snippet<[SelectRow<Item>[]]>;
+    /** Replaces the spinner shown while `loading` is true (or a `loadOptions` fetch is in flight). */
     loadingIconSnippet?: Snippet;
+    /** Replaces the icon inside each tag's remove button in multiple mode (the button and its `ariaRemoveItemLabel` stay). */
     multiClearIconSnippet?: Snippet;
+    /** Rendered inside the control before the selection and input — e.g. a search icon. */
     prependSnippet?: Snippet;
-    requiredSnippet?: Snippet<[SelectValue]>;
-    selectionSnippet?: Snippet<[SelectItem | SelectItem[], number?]>;
+    /**
+     * Replaces the hidden native `<select required>` fallback that blocks form
+     * submission while `required` and empty; receives the current value. An
+     * override owns the constraint-validation behavior.
+     */
+    requiredSnippet?: Snippet<[SelectValueProp<Item, Multiple> | undefined]>;
+    /** Receives one item at a time: the value in single mode, each tag in multiple mode. */
+    selectionSnippet?: Snippet<[NoInfer<Item>, number?]>;
+    /** Bindable, read-only: the container element, once mounted. */
     container?: HTMLDivElement;
+    /** Bindable, read-only: the text input element, once mounted. */
     input?: HTMLInputElement;
 }