@gooddata/sdk-ui-kit 11.42.0-alpha.2 → 11.42.0-alpha.3

package/esm/@ui/UiAutocomplete/UiAutocomplete.d.ts

@@ -0,0 +1,9 @@
+import type { IUiAutocompleteOption, IUiAutocompleteProps } from "./types.js";
+/**
+ * Async autocomplete: text input + sectioned listbox driven by a `loadOptions`
+ * loader. Implements the ARIA combobox+listbox APG pattern.
+ *
+ * @internal
+ */
+export declare function UiAutocomplete<T extends IUiAutocompleteOption = IUiAutocompleteOption>({ loadOptions, selectedIds, onSelect, debounceMs, messages, accessibilityConfig, dataTestId }: IUiAutocompleteProps<T>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=UiAutocomplete.d.ts.map

package/esm/@ui/UiAutocomplete/UiAutocomplete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UiAutocomplete.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiAutocomplete/UiAutocomplete.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAA0B,MAAM,YAAY,CAAC;AA+BtG;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,qBAAqB,GAAG,qBAAqB,EAAE,EACpF,WAAW,EACX,WAA6B,EAC7B,QAAQ,EACR,UAAgC,EAChC,QAAQ,EACR,mBAAmB,EACnB,UAAU,EACb,EAAE,oBAAoB,CAAC,CAAC,CAAC,2CAkOzB"}

package/esm/@ui/UiAutocomplete/UiAutocomplete.js

@@ -0,0 +1,230 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// (C) 2026 GoodData Corporation
+import { Fragment, useCallback, useId, useMemo } from "react";
+import { useIntl } from "react-intl";
+import { uiAutocompleteMessages } from "../../locales.js";
+import { bem } from "../@utils/bem.js";
+import { makeKeyboardNavigation } from "../@utils/keyboardNavigation.js";
+import { UiComboboxContextProvider } from "../UiCombobox/UiComboboxContext.js";
+import { UiComboboxInput } from "../UiCombobox/UiComboboxInput.js";
+import { UiComboboxListItem } from "../UiCombobox/UiComboboxListItem.js";
+import { UiComboboxPopup } from "../UiCombobox/UiComboboxPopup.js";
+import { useComboboxChrome } from "../UiCombobox/useComboboxChrome.js";
+import { UiSectionHeading } from "../UiSectionHeading/UiSectionHeading.js";
+import { useAsyncListSource } from "./useAsyncListSource.js";
+const { b, e } = bem("gd-ui-kit-autocomplete");
+const DEFAULT_DEBOUNCE_MS = 400;
+// Per-instance, per-generation synthetic id for the Load-more row; activating
+// it triggers a page fetch instead of `onSelect`. `listboxId` keeps it unique
+// across autocompletes on one page; `generation` makes it differ once the
+// query reloads, so a stale highlight can't carry onto the next query's row.
+const loadMoreId = (listboxId, generation) => `${listboxId}-load-more-${generation}`;
+// Stable default so an omitted `selectedIds` doesn't feed a fresh array into the
+// memo deps every render.
+const NO_SELECTED_IDS = [];
+// Mirrors `useCombobox`'s key map. Space, Home and End are left to the input
+// so the user can edit the query text natively.
+const autocompleteKeys = makeKeyboardNavigation({
+    onArrowDown: [{ code: "ArrowDown" }],
+    onArrowUp: [{ code: "ArrowUp" }],
+    onEnter: [{ code: ["Enter", "NumpadEnter"] }],
+    onEscape: [{ code: "Escape" }],
+});
+/**
+ * Async autocomplete: text input + sectioned listbox driven by a `loadOptions`
+ * loader. Implements the ARIA combobox+listbox APG pattern.
+ *
+ * @internal
+ */
+export function UiAutocomplete({ loadOptions, selectedIds = NO_SELECTED_IDS, onSelect, debounceMs = DEFAULT_DEBOUNCE_MS, messages, accessibilityConfig, dataTestId, }) {
+    const intl = useIntl();
+    const listboxId = useId();
+    const copy = useMemo(() => ({
+        searchPlaceholder: messages?.searchPlaceholder ?? intl.formatMessage(uiAutocompleteMessages.searchPlaceholder),
+        stateLoading: messages?.stateLoading ?? intl.formatMessage(uiAutocompleteMessages.stateLoading),
+        stateError: messages?.stateError ?? intl.formatMessage(uiAutocompleteMessages.stateError),
+        stateNoMatch: messages?.stateNoMatch ?? intl.formatMessage(uiAutocompleteMessages.stateNoMatch),
+        loadMore: messages?.loadMore ?? intl.formatMessage(uiAutocompleteMessages.loadMore),
+    }), [intl, messages]);
+    const source = useAsyncListSource(loadOptions, { debounceMs });
+    // The Load-more row's id is stamped with the load generation, so a highlight
+    // left on it before a query change can't re-attach to the next query's row
+    // (a constant id would survive and let Enter page the wrong query — the
+    // synthetic row is the one id the by-id highlight tracking can't otherwise
+    // tell apart across queries, since real options carry distinct ids).
+    const loadMoreRowId = loadMoreId(listboxId, source.generation);
+    const selectedIdSet = useMemo(() => new Set(selectedIds), [selectedIds]);
+    // Flat list of the rows the highlight can land on. Section headings and
+    // status rows render around it but never participate.
+    const focusableOptions = useMemo(() => {
+        const options = [];
+        for (const section of source.sections) {
+            for (const option of section.options) {
+                if (selectedIdSet.has(option.id)) {
+                    continue;
+                }
+                options.push({ id: option.id, label: option.label });
+            }
+        }
+        if (source.hasNextPage && source.status !== "loadingMore") {
+            options.push({ id: loadMoreRowId, label: copy.loadMore });
+        }
+        return options;
+    }, [source.sections, source.hasNextPage, source.status, selectedIdSet, copy.loadMore, loadMoreRowId]);
+    // Chrome tracks the highlight by row id, so a row that disappears (results
+    // change, Load-more row removed while its page loads) drops the highlight
+    // on its own — no manual resets to keep in sync.
+    const chrome = useComboboxChrome(focusableOptions);
+    const activeOptionData = useMemo(() => {
+        if (!chrome.activeOption) {
+            return undefined;
+        }
+        if (chrome.activeOption.id === loadMoreRowId) {
+            return "loadMore";
+        }
+        return findOptionById(source.sections, chrome.activeOption.id);
+    }, [chrome.activeOption, source.sections, loadMoreRowId]);
+    const handleSelect = useCallback((target) => {
+        if (target === "loadMore") {
+            // Drop the highlight while the next page loads: the Load-more row
+            // disappears, and a real option highlighted beforehand (e.g. clicked
+            // Load-more without hovering it first) must not stay Enter-armed.
+            chrome.setActiveIndex(null);
+            source.loadMore();
+            return;
+        }
+        onSelect(target);
+        // Clear the input + re-prime the loader so the next open shows the
+        // unfiltered first page rather than the previous query's results.
+        source.reset();
+        chrome.setIsOpen(false);
+    }, [chrome, source, onSelect]);
+    // Reopening after a failed load re-runs it, so every open path (click, type,
+    // and the keyboard arrows below) routes through this first to recover.
+    const retryIfErrored = useCallback(() => {
+        if (!chrome.isOpen && source.status === "error") {
+            source.retry();
+        }
+    }, [chrome.isOpen, source]);
+    const onInputKeyDown = useMemo(() => {
+        const onEnter = chrome.isOpen && activeOptionData ? () => handleSelect(activeOptionData) : undefined;
+        // Leave Escape unhandled when idle so an enclosing modal can dismiss.
+        const hasSomethingToClose = chrome.isOpen || source.inputValue.length > 0;
+        const onEscape = hasSomethingToClose
+            ? (event) => {
+                // Stop the native event too so an enclosing UiModalDialog's
+                // document Escape listener doesn't dismiss the whole dialog.
+                event.nativeEvent.stopPropagation();
+                if (chrome.isOpen) {
+                    chrome.setIsOpen(false);
+                    return;
+                }
+                source.reset();
+            }
+            : undefined;
+        return autocompleteKeys({
+            onArrowDown: () => {
+                retryIfErrored();
+                chrome.focusByDelta(1);
+            },
+            onArrowUp: () => {
+                retryIfErrored();
+                chrome.focusByDelta(-1);
+            },
+            onEnter,
+            onEscape,
+        });
+    }, [chrome, source, activeOptionData, handleSelect, retryIfErrored]);
+    const selectOptionFromContext = useCallback((option) => {
+        if (option.id === loadMoreRowId) {
+            handleSelect("loadMore");
+            return;
+        }
+        const resolved = findOptionById(source.sections, option.id);
+        if (resolved) {
+            handleSelect(resolved);
+        }
+    }, [handleSelect, source.sections, loadMoreRowId]);
+    // Stay visible across loading / error / no-match so the status row reaches
+    // the user; the sync combobox's "hide when empty" default does not apply here.
+    const shouldRenderPopup = chrome.isOpen;
+    const setIsOpen = useCallback((open) => {
+        if (open) {
+            retryIfErrored();
+        }
+        chrome.setIsOpen(open);
+    }, [chrome, retryIfErrored]);
+    const state = useMemo(() => ({
+        inputValue: source.inputValue,
+        onInputChange: (next) => {
+            source.setInputValue(next);
+            setIsOpen(true);
+        },
+        onInputKeyDown,
+        onInputBlur: () => chrome.setIsOpen(false),
+        availableOptions: focusableOptions,
+        activeIndex: chrome.activeIndex,
+        setActiveIndex: chrome.setActiveIndex,
+        activeOption: chrome.activeOption,
+        selectedOption: undefined,
+        selectOption: selectOptionFromContext,
+        isOpen: chrome.isOpen,
+        setIsOpen,
+        shouldRenderPopup,
+        anchorRef: chrome.anchorRef,
+        registerItemRef: chrome.registerItemRef,
+        creatable: false,
+        listboxId,
+    }), [
+        chrome,
+        source,
+        setIsOpen,
+        focusableOptions,
+        shouldRenderPopup,
+        onInputKeyDown,
+        selectOptionFromContext,
+        listboxId,
+    ]);
+    const visibleSections = source.sections
+        .map((section) => ({
+        ...section,
+        options: section.options.filter((o) => !selectedIdSet.has(o.id)),
+    }))
+        .filter((section) => section.options.length > 0);
+    // "No matching options" must mean the search found nothing — not that every
+    // match was hidden because it's already selected (a successful search). Key
+    // it off the loader's own result, before the selected-id filter.
+    const loaderReturnedNothing = source.sections.every((section) => section.options.length === 0);
+    const showEmptyState = source.status === "idle" && loaderReturnedNothing && !source.hasNextPage;
+    return (_jsx("div", { className: b(), "data-testid": dataTestId, children: _jsxs(UiComboboxContextProvider, { state: state, children: [
+                _jsx(UiComboboxInput, { placeholder: copy.searchPlaceholder, accessibilityConfig: accessibilityConfig }), _jsx(UiComboboxPopup, { children: _jsxs("ul", { className: e("list"), role: "listbox", id: listboxId, tabIndex: -1, children: [source.status === "loading" ? _jsx(StatusRow, { text: copy.stateLoading }) : null, source.status === "error" ? _jsx(StatusRow, { text: copy.stateError }) : null, visibleSections.length > 0 ? (_jsx(Sections, { sections: visibleSections, focusableOptions: focusableOptions })) : null, source.hasNextPage && source.status !== "loadingMore" ? (_jsx(LoadMoreRow, { id: loadMoreRowId, index: focusableOptions.findIndex((o) => o.id === loadMoreRowId), label: copy.loadMore })) : null, source.status === "loadingMore" ? _jsx(StatusRow, { text: copy.stateLoading }) : null, showEmptyState ? _jsx(StatusRow, { text: copy.stateNoMatch }) : null] }) })
+            ] }) }));
+}
+// `index` on each item must be its position in `focusableOptions` — chrome's
+// active-index navigation and item-ref registry are keyed off that.
+function Sections({ sections, focusableOptions, }) {
+    return sections.map((section) => (_jsxs(Fragment, { children: [
+            _jsx("li", { role: "presentation", className: e("section-header"), children: _jsx(UiSectionHeading, { label: section.label }) }), section.options.map((option) => {
+                const index = focusableOptions.findIndex((o) => o.id === option.id);
+                if (index < 0) {
+                    return null;
+                }
+                return (_jsxs(UiComboboxListItem, { option: { id: option.id, label: option.label }, index: index, className: e("option"), children: [
+                        _jsx("span", { className: e("option-label"), children: option.label }), option.secondaryText ? (_jsx("span", { className: e("option-secondary"), children: option.secondaryText })) : null] }, option.id));
+            })] }, section.id)));
+}
+function StatusRow({ text }) {
+    return (_jsx("li", { role: "presentation", className: e("state"), children: text }));
+}
+function LoadMoreRow({ id, index, label }) {
+    return (_jsx(UiComboboxListItem, { option: { id, label }, index: index, className: e("load-more"), children: _jsx("span", { children: label }) }));
+}
+function findOptionById(sections, id) {
+    for (const section of sections) {
+        const found = section.options.find((o) => o.id === id);
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}

package/esm/@ui/UiAutocomplete/types.d.ts

@@ -0,0 +1,61 @@
+import { type IAccessibilityConfigBase } from "../../typings/accessibility.js";
+/**
+ * Minimal option shape; specialized pickers map their domain objects onto it.
+ *
+ * @internal
+ */
+export interface IUiAutocompleteOption {
+    id: string;
+    label: string;
+    /** Secondary label rendered muted next to the primary label. */
+    secondaryText?: string;
+}
+/** @internal */
+export interface IUiAutocompleteSection<T extends IUiAutocompleteOption = IUiAutocompleteOption> {
+    id: string;
+    label: string;
+    options: T[];
+}
+/**
+ * User-facing copy overrides. Omitted fields fall back to the kit default.
+ *
+ * @internal
+ */
+export interface IUiAutocompleteMessages {
+    searchPlaceholder?: string;
+    stateLoading?: string;
+    stateError?: string;
+    stateNoMatch?: string;
+    loadMore?: string;
+}
+/** @internal */
+export interface IUiAutocompleteLoadResult<T extends IUiAutocompleteOption = IUiAutocompleteOption> {
+    sections: IUiAutocompleteSection<T>[];
+    /** Show a "Load more" row whose activation calls the loader with the next page. */
+    hasNextPage?: boolean;
+}
+/** @internal */
+export interface IUiAutocompleteProps<T extends IUiAutocompleteOption = IUiAutocompleteOption> {
+    /**
+     * Called with the debounced search and zero-based `page` index. Page 0
+     * fires on every query change; subsequent pages fire on Load-more.
+     *
+     * Must be referentially stable (memoize with `useCallback`) — it is a
+     * fetch dependency, so a new identity each render re-runs the page-0 query.
+     */
+    loadOptions: (search: string, page: number) => Promise<IUiAutocompleteLoadResult<T>>;
+    /** Filtered out of the dropdown so the user cannot pick the same option twice. */
+    selectedIds?: ReadonlyArray<string>;
+    onSelect: (option: T) => void;
+    /** Debounce delay for the input → loader path. Defaults to 400 ms. */
+    debounceMs?: number;
+    messages?: IUiAutocompleteMessages;
+    /**
+     * Forwarded to the search input for the accessible name / description.
+     * The combobox-internal attributes (`role`, `ariaExpanded`, `ariaControls`,
+     * `ariaAutocomplete`) are owned by the component and cannot be overridden.
+     */
+    accessibilityConfig?: IAccessibilityConfigBase;
+    dataTestId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/esm/@ui/UiAutocomplete/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiAutocomplete/types.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,gBAAgB;AAChB,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,qBAAqB,GAAG,qBAAqB;IAC3F,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,CAAC,EAAE,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACpC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gBAAgB;AAChB,MAAM,WAAW,yBAAyB,CAAC,CAAC,SAAS,qBAAqB,GAAG,qBAAqB;IAC9F,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;IACtC,mFAAmF;IACnF,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,gBAAgB;AAChB,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,qBAAqB,GAAG,qBAAqB;IACzF;;;;;;OAMG;IACH,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAAC;IACrF,kFAAkF;IAClF,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;IAC9B,wEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,wBAAwB,CAAC;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/esm/@ui/UiAutocomplete/types.js

@@ -0,0 +1,2 @@
+// (C) 2026 GoodData Corporation
+export {};

package/esm/@ui/UiAutocomplete/useAsyncListSource.d.ts

@@ -0,0 +1,42 @@
+import type { IUiAutocompleteOption, IUiAutocompleteSection } from "./types.js";
+type LoadResult<T extends IUiAutocompleteOption> = {
+    sections: IUiAutocompleteSection<T>[];
+    hasNextPage?: boolean;
+};
+/** @internal */
+export type AsyncListSourceLoader<T extends IUiAutocompleteOption> = (search: string, page: number) => Promise<LoadResult<T>>;
+/** @internal */
+export interface IUseAsyncListSourceOptions {
+    debounceMs: number;
+}
+/**
+ * `loadingMore` keeps prior pages visible while the next page is in flight;
+ * `error` blanks out the list.
+ *
+ * @internal
+ */
+export type AsyncListStatus = "loading" | "loadingMore" | "idle" | "error";
+/** @internal */
+export interface IAsyncListSource<T extends IUiAutocompleteOption> {
+    inputValue: string;
+    setInputValue: (next: string) => void;
+    sections: IUiAutocompleteSection<T>[];
+    status: AsyncListStatus;
+    hasNextPage: boolean;
+    loadMore: () => void;
+    reset: () => void;
+    /** Re-run the current page-0 query — used to recover from an error state. */
+    retry: () => void;
+    /** Increments on each page-0 load; lets callers tag per-query synthetic rows. */
+    generation: number;
+}
+/**
+ * Async data source for an autocomplete-shaped picker: debounce via
+ * `useDebouncedState`, fetching with stale-result protection via
+ * `useCancelablePromise`, section merge on pagination.
+ *
+ * @internal
+ */
+export declare function useAsyncListSource<T extends IUiAutocompleteOption>(loadOptions: AsyncListSourceLoader<T>, { debounceMs }: IUseAsyncListSourceOptions): IAsyncListSource<T>;
+export {};
+//# sourceMappingURL=useAsyncListSource.d.ts.map

package/esm/@ui/UiAutocomplete/useAsyncListSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAsyncListSource.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiAutocomplete/useAsyncListSource.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEhF,KAAK,UAAU,CAAC,CAAC,SAAS,qBAAqB,IAAI;IAC/C,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,gBAAgB;AAChB,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,qBAAqB,IAAI,CACjE,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,KACX,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAE5B,gBAAgB;AAChB,MAAM,WAAW,0BAA0B;IACvC,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3E,gBAAgB;AAChB,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,qBAAqB;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;IACtC,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,+EAA6E;IAC7E,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACtB;AAeD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,qBAAqB,EAC9D,WAAW,EAAE,qBAAqB,CAAC,CAAC,CAAC,EACrC,EAAE,UAAU,EAAE,EAAE,0BAA0B,GAC3C,gBAAgB,CAAC,CAAC,CAAC,CAqHrB"}

package/esm/@ui/UiAutocomplete/useAsyncListSource.js

@@ -0,0 +1,112 @@
+// (C) 2026 GoodData Corporation
+import { useCallback, useMemo, useState } from "react";
+import { useCancelablePromise, useDebouncedState } from "@gooddata/sdk-ui";
+/**
+ * Async data source for an autocomplete-shaped picker: debounce via
+ * `useDebouncedState`, fetching with stale-result protection via
+ * `useCancelablePromise`, section merge on pagination.
+ *
+ * @internal
+ */
+export function useAsyncListSource(loadOptions, { debounceMs }) {
+    const [inputValue, setInputValue, debouncedQuery, setInputValueImmediate] = useDebouncedState("", debounceMs);
+    // Bumping `retryToken` re-runs page-0 even when the query is unchanged, so a
+    // failed load can recover (e.g. when the popup is reopened) without the user
+    // having to edit the search text.
+    const [retryToken, setRetryToken] = useState(0);
+    const retry = useCallback(() => setRetryToken((t) => t + 1), []);
+    // Each page-0 load bumps the generation; Load-more pages are tagged with the
+    // generation they belong to and ignored once it advances. Counting loads
+    // (not comparing result objects) stays correct even if a loader returns the
+    // same object for a repeated query.
+    const [generation, setGeneration] = useState(0);
+    const queryLoad = useCancelablePromise({ promise: () => loadOptions(debouncedQuery, 0), onSuccess: () => setGeneration((g) => g + 1) }, [debouncedQuery, loadOptions, retryToken]);
+    const [paginationState, setPagination] = useState(null);
+    const pagination = paginationState?.generation === generation ? paginationState : null;
+    const pendingPage = pagination?.pendingPage ?? null;
+    // While the typed value is ahead of the debounced one the fetch has not
+    // started yet, but the UI must already report loading (and below, drop the
+    // sections) so the previous query's options are not left clickable.
+    const isDebouncing = inputValue !== debouncedQuery;
+    const isQueryLoading = queryLoad.status === "pending" || queryLoad.status === "loading";
+    useCancelablePromise({
+        // Hold pagination until page-0 of the current query has settled, so a
+        // query change mid-pagination can't fetch the new query at an old page.
+        promise: pendingPage == null || isDebouncing || isQueryLoading
+            ? null
+            : () => loadOptions(debouncedQuery, pendingPage),
+        onSuccess: (result) => setPagination((prev) => prev?.pendingPage == null
+            ? prev
+            : {
+                generation: prev.generation,
+                sections: mergeSections(prev.sections, result.sections),
+                pagesLoaded: prev.pagesLoaded + 1,
+                hasNextPage: !!result.hasNextPage,
+                pendingPage: null,
+            }),
+        // Keep the already-loaded pages; dropping back to idle re-shows the
+        // Load-more row so the user can retry the failed page.
+        onError: () => setPagination((prev) => (prev ? { ...prev, pendingPage: null } : prev)),
+    }, [pendingPage, debouncedQuery, loadOptions, isDebouncing, isQueryLoading]);
+    const status = isDebouncing || isQueryLoading
+        ? "loading"
+        : queryLoad.status === "error"
+            ? "error"
+            : pendingPage == null
+                ? "idle"
+                : "loadingMore";
+    const sections = useMemo(() => {
+        if (status === "loading" || status === "error" || queryLoad.result === undefined) {
+            return [];
+        }
+        return pagination
+            ? mergeSections(queryLoad.result.sections, pagination.sections)
+            : queryLoad.result.sections;
+    }, [status, queryLoad.result, pagination]);
+    const hasNextPage = (status === "idle" || status === "loadingMore") &&
+        (pagination ? pagination.hasNextPage : !!queryLoad.result?.hasNextPage);
+    const loadMore = useCallback(() => {
+        if (status !== "idle" || !hasNextPage) {
+            return;
+        }
+        setPagination({
+            generation,
+            sections: pagination?.sections ?? [],
+            pagesLoaded: pagination?.pagesLoaded ?? 0,
+            hasNextPage,
+            pendingPage: (pagination?.pagesLoaded ?? 0) + 1,
+        });
+    }, [status, hasNextPage, generation, pagination]);
+    // `setInputValueImmediate` from useDebouncedState isn't memoized, but it only
+    // delegates to stable `useState` setters, so omitting it keeps `reset`
+    // referentially stable without going stale.
+    const reset = useCallback(() => {
+        setInputValueImmediate("");
+        setPagination(null);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return useMemo(() => ({
+        inputValue,
+        setInputValue,
+        sections,
+        status,
+        hasNextPage,
+        loadMore,
+        reset,
+        retry,
+        generation,
+    }), [inputValue, setInputValue, sections, status, hasNextPage, loadMore, reset, retry, generation]);
+}
+function mergeSections(current, incoming) {
+    const merged = current.map((s) => ({ ...s, options: [...s.options] }));
+    for (const next of incoming) {
+        const existing = merged.find((s) => s.id === next.id);
+        if (existing) {
+            existing.options.push(...next.options);
+        }
+        else {
+            merged.push({ ...next, options: [...next.options] });
+        }
+    }
+    return merged;
+}

package/esm/@ui/UiCombobox/UiComboboxInput.d.ts

@@ -1,8 +1,13 @@
 import { type FocusEvent, type KeyboardEvent, type MouseEvent } from "react";
+import { type IAccessibilityConfigBase } from "../../typings/accessibility.js";
 /** @internal */
 export interface IUiComboboxInputProps {
-    /** Accessible name for the input. */
-    "aria-label"?: string;
+    /**
+     * Accessible name/description for the input (e.g. `ariaLabel`,
+     * `ariaDescribedBy`). The combobox role and listbox-wiring attributes are
+     * owned by the component and override anything passed here.
+     */
+    accessibilityConfig?: IAccessibilityConfigBase;
     /** Visible placeholder. */
     placeholder?: string;
     /** Form field name forwarded to the underlying input. */

package/esm/@ui/UiCombobox/UiComboboxInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UiComboboxInput.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiCombobox/UiComboboxInput.tsx"],"names":[],"mappings":"AAEA,OAAO,EACH,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,UAAU,EAIlB,MAAM,OAAO,CAAC;AAMf,gBAAgB;AAChB,MAAM,WAAW,qBAAqB;IAClC,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IAC7D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IACxD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IACvD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,oHAsF3B,CAAC"}
+{"version":3,"file":"UiComboboxInput.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiCombobox/UiComboboxInput.tsx"],"names":[],"mappings":"AAEA,OAAO,EACH,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,UAAU,EAIlB,MAAM,OAAO,CAAC;AAEf,OAAO,EAAE,KAAK,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAK/E,gBAAgB;AAChB,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,wBAAwB,CAAC;IAC/C,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IAC7D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IACxD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IACvD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,oHAsF3B,CAAC"}

package/esm/@ui/UiCombobox/UiComboboxInput.js

@@ -10,7 +10,7 @@ import { useComboboxState } from "./UiComboboxContext.js";
  * @internal
  */
 export const UiComboboxInput = forwardRef(function UiComboboxInput(props, forwardedRef) {
-    const { "aria-label": ariaLabel, placeholder, name, autoFocus, onKeyDown: callerOnKeyDown, onFocus: callerOnFocus, onBlur: callerOnBlur, onClick: callerOnClick, dataTestId, } = props;
+    const { accessibilityConfig, placeholder, name, autoFocus, onKeyDown: callerOnKeyDown, onFocus: callerOnFocus, onBlur: callerOnBlur, onClick: callerOnClick, dataTestId, } = props;
     const { inputValue, onInputChange, onInputKeyDown, onInputBlur, isOpen, setIsOpen, anchorRef, activeOption, listboxId, } = useComboboxState();
     const handleKeyDown = useCallback((event) => {
         onInputKeyDown(event);
@@ -33,12 +33,12 @@ export const UiComboboxInput = forwardRef(function UiComboboxInput(props, forwar
         // Browser autofill would overlap the listbox; the combobox
         // owns its own typeahead so we suppress all native suggestions.
         autoComplete: "off", autoCapitalize: "none", autoCorrect: "off", dataTestId: dataTestId, onKeyDown: handleKeyDown, onFocus: callerOnFocus, onBlur: handleBlur, onClick: handleClick, accessibilityConfig: {
+            ...accessibilityConfig,
             role: "combobox",
             ariaAutocomplete: "list",
             ariaExpanded: isOpen,
             ariaActiveDescendant: activeOption?.id,
             ariaHaspopup: "listbox",
             ariaControls: listboxId,
-            ariaLabel,
         } }));
 });

package/esm/@ui/UiCombobox/useCombobox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCombobox.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiCombobox/useCombobox.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAkBtE,gBAAgB;AAChB,wBAAgB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,CA+EvE"}
+{"version":3,"file":"useCombobox.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiCombobox/useCombobox.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAkBtE,gBAAgB;AAChB,wBAAgB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,CAuEvE"}

package/esm/@ui/UiCombobox/useCombobox.js

@@ -15,23 +15,16 @@ const comboboxKeys = makeKeyboardNavigation({
 export function useCombobox(params) {
     const { value, defaultValue = "", onValueChange, options, creatable = false } = params;
     const listboxId = useId();
-    const chrome = useComboboxChrome();
     const selection = useComboboxSelection({
         options,
         value,
         defaultValue,
         onValueChange,
         creatable,
-        setIsOpen: chrome.setIsOpen,
-        setActiveIndex: chrome.setActiveIndex,
+        setIsOpen: (open) => chrome.setIsOpen(open),
     });
-    // Clamp on read so a filter that shrinks the list doesn't leave us
-    // pointing past the end (Enter would otherwise be a silent no-op).
-    const optionCount = selection.availableOptions.length;
-    const safeActiveIndex = chrome.activeIndex == null ? null : Math.min(chrome.activeIndex, optionCount - 1);
-    const activeOption = safeActiveIndex == null || optionCount === 0
-        ? undefined
-        : selection.availableOptions[safeActiveIndex];
+    const chrome = useComboboxChrome(selection.availableOptions);
+    const activeOption = chrome.activeOption;
     const onInputKeyDown = useMemo(() => {
         // Leave Enter unhandled when there's no selectable target so creatable
         // flows like UiTags (add tag on unhandled Enter) can react to it.
@@ -53,12 +46,12 @@ export function useCombobox(params) {
             }
             : undefined;
         return comboboxKeys({
-            onArrowDown: () => chrome.focusByDelta(1, optionCount),
-            onArrowUp: () => chrome.focusByDelta(-1, optionCount),
+            onArrowDown: () => chrome.focusByDelta(1),
+            onArrowUp: () => chrome.focusByDelta(-1),
             onEnter,
             onEscape,
         });
-    }, [chrome, selection, activeOption, optionCount]);
+    }, [chrome, selection, activeOption]);
     return useMemo(() => ({
         availableOptions: selection.availableOptions,
         inputValue: selection.inputValue,
@@ -74,8 +67,8 @@ export function useCombobox(params) {
         selectOption: selection.selectOption,
         anchorRef: chrome.anchorRef,
         registerItemRef: chrome.registerItemRef,
-        shouldRenderPopup: optionCount > 0,
+        shouldRenderPopup: selection.availableOptions.length > 0,
         creatable,
         listboxId,
-    }), [chrome, selection, onInputKeyDown, activeOption, creatable, listboxId, optionCount]);
+    }), [chrome, selection, onInputKeyDown, activeOption, creatable, listboxId]);
 }

package/esm/@ui/UiCombobox/useComboboxChrome.d.ts

@@ -1,9 +1,20 @@
-import type { IUiComboboxState } from "./types.js";
+import type { IUiComboboxOption, IUiComboboxState } from "./types.js";
 type IUseComboboxChromeReturn = Pick<IUiComboboxState, "isOpen" | "setIsOpen" | "activeIndex" | "setActiveIndex" | "anchorRef" | "registerItemRef"> & {
-    /** Open the popup if needed and move highlight by `delta`, wrapping at `total`. */
-    focusByDelta: (delta: 1 | -1, total: number) => void;
+    /** The currently highlighted option, or undefined. */
+    activeOption: IUiComboboxOption | undefined;
+    /** Open the popup if needed and move the highlight by `delta`, wrapping around. */
+    focusByDelta: (delta: 1 | -1) => void;
 };
-/** @internal */
-export declare function useComboboxChrome(): IUseComboboxChromeReturn;
+/**
+ * Owns popup open/close, highlight, and scroll. The highlight is tracked by
+ * option **id**, not index: when the option list changes (async results arrive,
+ * a row is filtered out) a highlighted row that's gone simply resolves to no
+ * index, so the highlight can never point at a different row than the user
+ * navigated to. Callers pass the current `options` so the id ⇄ index mapping
+ * and `focusByDelta` wrapping stay in sync with what's rendered.
+ *
+ * @internal
+ */
+export declare function useComboboxChrome(options: IUiComboboxOption[]): IUseComboboxChromeReturn;
 export {};
 //# sourceMappingURL=useComboboxChrome.d.ts.map

package/esm/@ui/UiCombobox/useComboboxChrome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useComboboxChrome.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiCombobox/useComboboxChrome.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,KAAK,wBAAwB,GAAG,IAAI,CAChC,gBAAgB,EAChB,QAAQ,GAAG,WAAW,GAAG,aAAa,GAAG,gBAAgB,GAAG,WAAW,GAAG,iBAAiB,CAC9F,GAAG;IACA,mFAAmF;IACnF,YAAY,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACxD,CAAC;AAEF,gBAAgB;AAChB,wBAAgB,iBAAiB,IAAI,wBAAwB,CAmE5D"}
+{"version":3,"file":"useComboboxChrome.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiCombobox/useComboboxChrome.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEtE,KAAK,wBAAwB,GAAG,IAAI,CAChC,gBAAgB,EAChB,QAAQ,GAAG,WAAW,GAAG,aAAa,GAAG,gBAAgB,GAAG,WAAW,GAAG,iBAAiB,CAC9F,GAAG;IACA,sDAAsD;IACtD,YAAY,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC5C,mFAAmF;IACnF,YAAY,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC;CACzC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,wBAAwB,CA6FxF"}