@gooddata/sdk-ui-kit 11.42.0-alpha.1 → 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,6 +1,29 @@
-import { type InputHTMLAttributes } from "react";
+import { type FocusEvent, type KeyboardEvent, type MouseEvent } from "react";
+import { type IAccessibilityConfigBase } from "../../typings/accessibility.js";
 /** @internal */
-export type UiComboboxInputProps = InputHTMLAttributes<HTMLInputElement>;
-/** @internal */
-export declare const UiComboboxInput: import("react").ForwardRefExoticComponent<UiComboboxInputProps & import("react").RefAttributes<HTMLInputElement>>;
+export interface IUiComboboxInputProps {
+    /**
+     * 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. */
+    name?: string;
+    autoFocus?: boolean;
+    onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
+    onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
+    onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
+    onClick?: (event: MouseEvent<HTMLInputElement>) => void;
+    dataTestId?: string;
+}
+/**
+ * Binds `UiTextInput` to the surrounding `UiCombobox` state: value, keyboard
+ * handler, open/close, ARIA combobox+listbox attributes.
+ *
+ * @internal
+ */
+export declare const UiComboboxInput: import("react").ForwardRefExoticComponent<IUiComboboxInputProps & import("react").RefAttributes<HTMLInputElement>>;
 //# sourceMappingURL=UiComboboxInput.d.ts.map

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,EAGH,KAAK,mBAAmB,EAG3B,MAAM,OAAO,CAAC;AAQf,gBAAgB;AAChB,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;AAEzE,gBAAgB;AAChB,eAAO,MAAM,eAAe,mHAqD3B,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

@@ -1,37 +1,44 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-// (C) 2025 GoodData Corporation
-import { forwardRef, } from "react";
-import { useMergeRefs } from "@floating-ui/react";
-import cx from "classnames";
-import { e } from "./comboboxBem.js";
+// (C) 2025-2026 GoodData Corporation
+import { forwardRef, useCallback, } from "react";
+import { UiTextInput } from "../UiTextInput/UiTextInput.js";
 import { useComboboxState } from "./UiComboboxContext.js";
-/** @internal */
+/**
+ * Binds `UiTextInput` to the surrounding `UiCombobox` state: value, keyboard
+ * handler, open/close, ARIA combobox+listbox attributes.
+ *
+ * @internal
+ */
 export const UiComboboxInput = forwardRef(function UiComboboxInput(props, forwardedRef) {
-    const { type, className, ...htmlInputProps } = props;
-    const { inputValue, onInputChange, onInputKeyDown, onInputBlur, setReferenceRef, getReferenceProps, activeOption, } = useComboboxState();
-    const ref = useMergeRefs([forwardedRef, setReferenceRef]);
-    const referenceProps = getReferenceProps({
-        ...htmlInputProps,
-        autoComplete: "off",
-        autoCapitalize: "none",
-        autoCorrect: "off",
-        // Most of the aria attributes already come from `getReferenceProps`
-        "aria-activedescendant": activeOption?.id,
-        "aria-autocomplete": "list",
-        onKeyDown: handleKeyDown,
-        onBlur: handleBlur,
-    });
-    function handleChange(event) {
-        onInputChange(event.target.value);
-        htmlInputProps.onChange?.(event);
-    }
-    function handleKeyDown(event) {
+    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);
-        htmlInputProps.onKeyDown?.(event);
-    }
-    function handleBlur(event) {
+        if (!event.isDefaultPrevented()) {
+            callerOnKeyDown?.(event);
+        }
+    }, [onInputKeyDown, callerOnKeyDown]);
+    const handleBlur = useCallback((event) => {
         onInputBlur();
-        htmlInputProps.onBlur?.(event);
-    }
-    return (_jsx("input", { ...referenceProps, ref: ref, className: cx(e("input"), className), type: type ?? "text", value: inputValue, onChange: handleChange }));
+        callerOnBlur?.(event);
+    }, [onInputBlur, callerOnBlur]);
+    // Click toggles open state (matches floating-ui's default `useClick`),
+    // so the user can also click to close. Focus alone doesn't open —
+    // Tab / programmatic focus shouldn't expand the listbox.
+    const handleClick = useCallback((event) => {
+        setIsOpen(!isOpen);
+        callerOnClick?.(event);
+    }, [isOpen, setIsOpen, callerOnClick]);
+    return (_jsx(UiTextInput, { inputRef: forwardedRef, wrapperRef: anchorRef, value: inputValue, onChange: onInputChange, name: name, placeholder: placeholder, autoFocus: autoFocus, 
+        // 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,
+        } }));
 });

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

@@ -7,6 +7,6 @@ import { useComboboxState } from "./UiComboboxContext.js";
 import { UiComboboxListItem } from "./UiComboboxListItem.js";
 /** @internal */
 export function UiComboboxList({ children, className, ...htmlProps }) {
-    const { availableOptions } = useComboboxState();
-    return (_jsx("ul", { role: "listbox", ...htmlProps, className: cx(e("list"), className), tabIndex: -1, children: availableOptions.map((option, index) => children ? (_jsx(Fragment, { children: children(option, index) }, option.id)) : (_jsx(UiComboboxListItem, { option: option, index: index }, option.id))) }));
+    const { availableOptions, listboxId } = useComboboxState();
+    return (_jsx("ul", { role: "listbox", ...htmlProps, id: listboxId, className: cx(e("list"), className), tabIndex: -1, children: availableOptions.map((option, index) => children ? (_jsx(Fragment, { children: children(option, index) }, option.id)) : (_jsx(UiComboboxListItem, { option: option, index: index }, option.id))) }));
 }

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

@@ -11,28 +11,18 @@ type UiComboboxListItemImplProps = IUiComboboxListItemProps & {
     isActive: boolean;
     isSelected: boolean;
     isDisabled: boolean;
-    getItemProps: IUiComboboxState["getItemProps"];
     registerItemRef: IUiComboboxState["registerItemRef"];
+    setActiveIndex: IUiComboboxState["setActiveIndex"];
     selectOption: IUiComboboxState["selectOption"];
 };
 export declare const UiComboboxListItemImpl: import("react").NamedExoticComponent<UiComboboxListItemImplProps>;
 /** @internal */
 export type UiComboboxListItemLabelProps = HTMLAttributes<HTMLSpanElement>;
-/**
- * Renders the primary label content within a combobox list item.
- * Use this component for composable customization of list item content.
- *
- * @internal
- */
+/** @internal */
 export declare function UiComboboxListItemLabel(props: UiComboboxListItemLabelProps): import("react/jsx-runtime").JSX.Element;
 /** @internal */
 export type UiComboboxListItemCreatableLabelProps = HTMLAttributes<HTMLSpanElement>;
-/**
- * Renders the "creatable" label suffix within a combobox list item.
- * Use this component for composable customization of list item content.
- *
- * @internal
- */
+/** @internal */
 export declare function UiComboboxListItemCreatableLabel(props: UiComboboxListItemCreatableLabelProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=UiComboboxListItem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"UiComboboxListItem.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiCombobox/UiComboboxListItem.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,OAAO,CAAC;AAKnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGtE,gBAAgB;AAChB,MAAM,WAAW,wBAAyB,SAAQ,cAAc,CAAC,aAAa,CAAC;IAC3E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,gBAAgB;AAChB,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,wBAAwB,2CAmBjE;AAED,KAAK,2BAA2B,GAAG,wBAAwB,GAAG;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;IAC/C,eAAe,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;IACrD,YAAY,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;CAClD,CAAC;AAEF,eAAO,MAAM,sBAAsB,mEAuDjC,CAAC;AAEH,gBAAgB;AAChB,MAAM,MAAM,4BAA4B,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;AAE3E;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,4BAA4B,2CAO1E;AAED,gBAAgB;AAChB,MAAM,MAAM,qCAAqC,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;AAEpF;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,qCAAqC,2CAO5F"}
+{"version":3,"file":"UiComboboxListItem.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiCombobox/UiComboboxListItem.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,OAAO,CAAC;AAKnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGtE,gBAAgB;AAChB,MAAM,WAAW,wBAAyB,SAAQ,cAAc,CAAC,aAAa,CAAC;IAC3E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,gBAAgB;AAChB,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,wBAAwB,2CAoBjE;AAED,KAAK,2BAA2B,GAAG,wBAAwB,GAAG;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,eAAe,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;IACrD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;IACnD,YAAY,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;CAClD,CAAC;AAEF,eAAO,MAAM,sBAAsB,mEAyDjC,CAAC;AAEH,gBAAgB;AAChB,MAAM,MAAM,4BAA4B,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;AAE3E,gBAAgB;AAChB,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,4BAA4B,2CAO1E;AAED,gBAAgB;AAChB,MAAM,MAAM,qCAAqC,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;AAEpF,gBAAgB;AAChB,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,qCAAqC,2CAO5F"}