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

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"}

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

@@ -1,18 +1,37 @@
 // (C) 2026 GoodData Corporation
 import { useCallback, useMemo, useRef, useState } from "react";
-/** @internal */
-export function useComboboxChrome() {
-    const [isOpen, setIsOpen] = useState(false);
-    const [activeIndex, setActiveIndex] = useState(null);
+/**
+ * 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 function useComboboxChrome(options) {
+    const [isOpen, setIsOpenState] = useState(false);
+    const [activeId, setActiveId] = useState(null);
+    // A highlight only has meaning while the popup is open, so closing always
+    // drops it — reopening then starts fresh. This is the single point that
+    // keeps a stale highlight from surviving Escape / blur / reset and being
+    // Enter-selected on the next open.
+    const setIsOpen = useCallback((open) => {
+        setIsOpenState(open);
+        if (!open) {
+            setActiveId(null);
+        }
+    }, []);
     const anchorRef = useRef(null);
     const itemRefs = useRef([]);
     // Target index for when the scroll request runs before the item mounts.
     const pendingScrollIndexRef = useRef(null);
+    const activeIndex = activeId == null ? null : options.findIndex((o) => o.id === activeId);
+    // findIndex returns -1 for a vanished row; surface that as "no highlight".
+    const safeActiveIndex = activeIndex != null && activeIndex >= 0 ? activeIndex : null;
+    const activeOption = safeActiveIndex == null ? undefined : options[safeActiveIndex];
     const scrollIndexIntoView = useCallback((index) => {
-        if (index == null) {
-            pendingScrollIndexRef.current = null;
-            return;
-        }
         const node = itemRefs.current[index];
         if (node) {
             pendingScrollIndexRef.current = null;
@@ -29,33 +48,42 @@ export function useComboboxChrome() {
             node.scrollIntoView({ block: "nearest" });
         }
     }, []);
-    const focusByDelta = useCallback((delta, total) => {
+    const setActiveIndex = useCallback((index) => setActiveId(index == null ? null : (options[index]?.id ?? null)), [options]);
+    const focusByDelta = useCallback((delta) => {
+        const total = options.length;
         if (total === 0) {
             setIsOpen(true);
             return;
         }
-        // When opening from a closed state, jump to the first / last item.
-        if (!isOpen) {
-            setIsOpen(true);
-            const next = delta === 1 ? 0 : total - 1;
-            setActiveIndex(next);
-            scrollIndexIntoView(next);
-            return;
-        }
-        // Clamp on read so a stale activeIndex from a shrunken list still
-        // produces a sensible wrap.
-        const current = activeIndex == null ? null : Math.min(activeIndex, total - 1);
-        const next = current == null ? (delta === 1 ? 0 : total - 1) : (current + delta + total) % total;
-        setActiveIndex(next);
+        // Resolve against the current list so a stale/removed highlight still
+        // produces a sensible next target.
+        const current = safeActiveIndex;
+        const next = !isOpen || current == null
+            ? delta === 1
+                ? 0
+                : total - 1
+            : (current + delta + total) % total;
+        setIsOpen(true);
+        setActiveId(options[next]?.id ?? null);
         scrollIndexIntoView(next);
-    }, [isOpen, activeIndex, scrollIndexIntoView]);
+    }, [isOpen, options, safeActiveIndex, scrollIndexIntoView, setIsOpen]);
     return useMemo(() => ({
         isOpen,
         setIsOpen,
-        activeIndex,
+        activeIndex: safeActiveIndex,
+        activeOption,
+        setActiveIndex,
+        anchorRef,
+        registerItemRef,
+        focusByDelta,
+    }), [
+        isOpen,
+        setIsOpen,
+        safeActiveIndex,
+        activeOption,
         setActiveIndex,
         anchorRef,
         registerItemRef,
         focusByDelta,
-    }), [isOpen, activeIndex, anchorRef, registerItemRef, focusByDelta]);
+    ]);
 }

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

@@ -7,18 +7,17 @@ export interface IUseComboboxSelectionParams {
     onValueChange?: (value: string) => void;
     creatable?: boolean;
     setIsOpen: (open: boolean) => void;
-    setActiveIndex: (index: number | null) => void;
 }
 /**
  * @internal
  */
-export declare function useComboboxSelection({ options, value, defaultValue, onValueChange, creatable, setIsOpen, setActiveIndex }: IUseComboboxSelectionParams): {
+export declare function useComboboxSelection({ options, value, defaultValue, onValueChange, creatable, setIsOpen }: IUseComboboxSelectionParams): {
     availableOptions: IUiComboboxOption[];
     inputValue: string;
     onInputChange: (next: string) => void;
     onInputBlur: () => void;
     selectedOption: IUiComboboxOption | undefined;
-    selectOption: (option: IUiComboboxOption, index?: number | undefined) => void;
+    selectOption: (option: IUiComboboxOption) => void;
     resetState: () => void;
 };
 //# sourceMappingURL=useComboboxSelection.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useComboboxSelection.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiCombobox/useComboboxSelection.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,gBAAgB;AAChB,MAAM,WAAW,2BAA2B;IACxC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CAClD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EACjC,OAAO,EACP,KAAK,EACL,YAAiB,EACjB,aAAa,EACb,SAAiB,EACjB,SAAS,EACT,cAAc,EACjB,EAAE,2BAA2B;;;;;;;;EAgF7B"}
+{"version":3,"file":"useComboboxSelection.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiCombobox/useComboboxSelection.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,gBAAgB;AAChB,MAAM,WAAW,2BAA2B;IACxC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EACjC,OAAO,EACP,KAAK,EACL,YAAiB,EACjB,aAAa,EACb,SAAiB,EACjB,SAAS,EACZ,EAAE,2BAA2B;;;;;;;;EA4E7B"}

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

@@ -4,14 +4,13 @@ import { normalizeValue } from "./utils.js";
 /**
  * @internal
  */
-export function useComboboxSelection({ options, value, defaultValue = "", onValueChange, creatable = false, setIsOpen, setActiveIndex, }) {
+export function useComboboxSelection({ options, value, defaultValue = "", onValueChange, creatable = false, setIsOpen, }) {
     const [inputValue, setInputValue] = useControlledValue({ value, defaultValue, onValueChange });
     const [selectedOption, setSelectedOption] = useState(undefined);
     const resetState = useCallback(() => {
         setInputValue(defaultValue);
-        setActiveIndex(null);
         setSelectedOption(undefined);
-    }, [defaultValue, setInputValue, setActiveIndex]);
+    }, [defaultValue, setInputValue]);
     const availableOptions = useMemo(() => {
         const value = normalizeValue(inputValue);
         const selectedValue = selectedOption ? normalizeValue(selectedOption.label) : undefined;
@@ -31,20 +30,17 @@ export function useComboboxSelection({ options, value, defaultValue = "", onValu
         }
         return matchedOptions;
     }, [options, inputValue, selectedOption, creatable]);
-    const selectOption = useCallback((option, index) => {
-        // Hover sets activeIndex without checking `disabled`, so without
+    const selectOption = useCallback((option) => {
+        // Hover sets the highlight without checking `disabled`, so without
         // this guard a disabled row could be Enter-confirmed even though
         // clicking it is blocked in the list item.
         if (option.disabled) {
             return;
         }
-        if (index !== undefined) {
-            setActiveIndex(index);
-        }
         setSelectedOption(option);
         setIsOpen(false);
         setInputValue(option.label);
-    }, [setActiveIndex, setIsOpen, setInputValue]);
+    }, [setIsOpen, setInputValue]);
     const onInputChange = useCallback((next) => {
         setInputValue(next);
         setIsOpen(true);

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

@@ -0,0 +1,73 @@
+import { type GranteeAvatarKind } from "../UiGranteeAvatar/UiGranteeAvatar.js";
+import { type PermissionMenuLevel } from "../UiPermissionMenu/UiPermissionMenu.js";
+/**
+ * One pickable user or group entry.
+ *
+ * @internal
+ */
+export interface IUiGranteeAsyncOption {
+    /** Stable identifier — used as the React key and as the value passed to `onSelect`. */
+    id: string;
+    /** Avatar variant. */
+    kind: GranteeAvatarKind;
+    /** Display name shown on the row. */
+    name: string;
+    /** Optional email subline (users only). */
+    email?: string;
+}
+/**
+ * A previously-picked grantee with its current permission level.
+ *
+ * @internal
+ */
+export interface IUiPickedGrantee extends IUiGranteeAsyncOption {
+    /** Permission level chosen for this grantee. Drives the row's permission menu trigger label. */
+    permissionLevel: PermissionMenuLevel;
+}
+/**
+ * Result returned by the consumer's loader: separate `groups` and `users` arrays
+ * so the dropdown can render the two sections independently. Either may be empty.
+ *
+ * @internal
+ */
+export interface IUiGranteeAsyncOptions {
+    groups: IUiGranteeAsyncOption[];
+    users: IUiGranteeAsyncOption[];
+}
+/**
+ * @internal
+ */
+export interface IUiGranteeAsyncPickerProps {
+    /**
+     * Loader called whenever the (debounced) search query changes. The empty
+     * string is passed on mount to populate the initial dropdown. Pagination
+     * is intentionally not exposed at this layer — the loader returns the
+     * full search result and the consumer caps backend results elsewhere.
+     */
+    loadOptions: (search: string) => Promise<IUiGranteeAsyncOptions>;
+    /**
+     * Grantees already picked. Rendered below the search input as `UiGranteeRow`s
+     * with a `UiPermissionMenu` trigger and a Remove action. Also filtered out
+     * of the dropdown so the user cannot pick the same grantee twice.
+     */
+    selectedGrantees?: ReadonlyArray<IUiPickedGrantee>;
+    /** Fires when the user picks an option from the dropdown. */
+    onSelect: (option: IUiGranteeAsyncOption) => void;
+    /** Fires when the user changes the permission level on a picked row. */
+    onPermissionChange?: (grantee: IUiPickedGrantee, next: PermissionMenuLevel) => void;
+    /** Fires when the user picks Remove access in the row's permission menu. */
+    onRemove?: (grantee: IUiPickedGrantee) => void;
+    /** Test id forwarded to the root element. */
+    dataTestId?: string;
+}
+/**
+ * Sectioned async grantee picker — specialization of `UiAutocomplete` for the
+ * share/access-control domain. Renders a search input with a dropdown split
+ * into `Groups` and `Users` sections, and a list of picked grantees below
+ * (each as a `UiGranteeRow` with a `UiPermissionMenu` trigger). The
+ * permission menu carries the Remove action; consumers wire it via `onRemove`.
+ *
+ * @internal
+ */
+export declare function UiGranteeAsyncPicker({ loadOptions, selectedGrantees, onSelect, onPermissionChange, onRemove, dataTestId }: IUiGranteeAsyncPickerProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=UiGranteeAsyncPicker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UiGranteeAsyncPicker.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiGranteeAsyncPicker/UiGranteeAsyncPicker.tsx"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE/E,OAAO,EAAE,KAAK,mBAAmB,EAAoB,MAAM,yCAAyC,CAAC;AAIrG;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IAClC,yFAAuF;IACvF,EAAE,EAAE,MAAM,CAAC;IACX,sBAAsB;IACtB,IAAI,EAAE,iBAAiB,CAAC;IACxB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,qBAAqB;IAC3D,gGAAgG;IAChG,eAAe,EAAE,mBAAmB,CAAC;CACxC;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACnC,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,KAAK,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACvC;;;;;OAKG;IACH,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACjE;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACnD,6DAA6D;IAC7D,QAAQ,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAClD,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACpF,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC/C,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAOD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,EACjC,WAAW,EACX,gBAAqB,EACrB,QAAQ,EACR,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACb,EAAE,0BAA0B,2CA2G5B"}

package/esm/@ui/UiGranteeAsyncPicker/UiGranteeAsyncPicker.js

@@ -0,0 +1,69 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// (C) 2026 GoodData Corporation
+import { useCallback, useMemo } from "react";
+import { useIntl } from "react-intl";
+import { olpAddGranteeDialogMessages, olpPermissionMessages, uiGranteeAsyncPickerMessages, } from "../../locales.js";
+import { bem } from "../@utils/bem.js";
+import { UiAutocomplete } from "../UiAutocomplete/UiAutocomplete.js";
+import { UiButton } from "../UiButton/UiButton.js";
+import { UiGranteeRow } from "../UiGranteeRow/UiGranteeRow.js";
+import { UiPermissionMenu } from "../UiPermissionMenu/UiPermissionMenu.js";
+const { b, e } = bem("gd-ui-kit-grantee-async-picker");
+/**
+ * Sectioned async grantee picker — specialization of `UiAutocomplete` for the
+ * share/access-control domain. Renders a search input with a dropdown split
+ * into `Groups` and `Users` sections, and a list of picked grantees below
+ * (each as a `UiGranteeRow` with a `UiPermissionMenu` trigger). The
+ * permission menu carries the Remove action; consumers wire it via `onRemove`.
+ *
+ * @internal
+ */
+export function UiGranteeAsyncPicker({ loadOptions, selectedGrantees = [], onSelect, onPermissionChange, onRemove, dataTestId, }) {
+    const intl = useIntl();
+    const groupsLabel = intl.formatMessage(uiGranteeAsyncPickerMessages.sectionGroups);
+    const usersLabel = intl.formatMessage(uiGranteeAsyncPickerMessages.sectionUsers);
+    const canViewLabel = intl.formatMessage(olpPermissionMessages.canView);
+    const canShareLabel = intl.formatMessage(olpPermissionMessages.canViewAndShare);
+    const selectedIds = useMemo(() => selectedGrantees.map((g) => g.id), [selectedGrantees]);
+    const adaptedLoadOptions = useCallback(async (search) => {
+        const { groups, users } = await loadOptions(search);
+        const sections = [];
+        if (groups.length > 0) {
+            sections.push({
+                id: "groups",
+                label: groupsLabel,
+                options: groups.map((g) => ({ id: g.id, label: g.name, grantee: g })),
+            });
+        }
+        if (users.length > 0) {
+            sections.push({
+                id: "users",
+                label: usersLabel,
+                options: users.map((u) => ({
+                    id: u.id,
+                    label: u.name,
+                    secondaryText: u.email,
+                    grantee: u,
+                })),
+            });
+        }
+        // The grantee picker doesn't paginate at the kit level — backend
+        // pagination, if any, is hidden inside the consumer's loader.
+        return { sections };
+    }, [loadOptions, groupsLabel, usersLabel]);
+    const handleSelect = useCallback((option) => {
+        onSelect(option.grantee);
+    }, [onSelect]);
+    const autocompleteMessages = useMemo(() => ({
+        searchPlaceholder: intl.formatMessage(uiGranteeAsyncPickerMessages.searchPlaceholder),
+        stateError: intl.formatMessage(uiGranteeAsyncPickerMessages.stateError),
+        stateNoMatch: intl.formatMessage(uiGranteeAsyncPickerMessages.stateNoMatch),
+    }), [intl]);
+    return (_jsxs("div", { className: b(), "data-testid": dataTestId, children: [
+            _jsx(UiAutocomplete, { loadOptions: adaptedLoadOptions, selectedIds: selectedIds, onSelect: handleSelect, messages: autocompleteMessages, accessibilityConfig: {
+                    ariaLabel: intl.formatMessage(olpAddGranteeDialogMessages.userOrGroup),
+                } }), selectedGrantees.length === 0 ? (_jsx("div", { className: e("empty-state"), children: intl.formatMessage(olpAddGranteeDialogMessages.emptyState) })) : null, selectedGrantees.length > 0 ? (_jsx("ul", { className: e("picked-list"), children: selectedGrantees.map((g) => {
+                    const triggerLabel = g.permissionLevel === "SHARE" ? canShareLabel : canViewLabel;
+                    return (_jsx("li", { className: e("picked-item"), children: _jsx(UiGranteeRow, { kind: g.kind, name: g.name, email: g.email, controls: _jsx(UiPermissionMenu, { selectedLevel: g.permissionLevel, onPermissionChange: (next) => onPermissionChange?.(g, next), onRemoveAccess: onRemove ? () => onRemove(g) : undefined, anchor: _jsx(UiButton, { label: triggerLabel, variant: "dropdownInline", size: "small", iconAfter: "navigateDown" }) }) }) }, g.id));
+                }) })) : null] }));
+}

package/esm/@ui/UiIcon/icons.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"icons.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiIcon/icons.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CA4+BjD,CAAC"}
+{"version":3,"file":"icons.d.ts","sourceRoot":"","sources":["../../../src/@ui/UiIcon/icons.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CAk/BjD,CAAC"}