nexus-shared 1.1.20 → 2.0.0

package/dist/Components/Inputs/Dropdown.js

@@ -0,0 +1,839 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconAlertCircle, iconChevronDown, iconLoader2, iconX, InlineIcon } from "nexus-icons";
+import { isValidElement, useDeferredValue, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { columnTrack, defaultSearchKeys, filterItems, foldSearchText, indexItems, isDisabledItem, isInactiveItem, itemLabel, itemValue, matchesSearch, optionKey, readField, searchWords, toValueList, } from "../../Helpers/DropdownHelpers.js";
+import { followAnchor, isPopoverOpen, placeListPanel } from "../../Helpers/PopoverHelpers.js";
+import { DEFAULT_FIELD_NAME, validateSelection } from "../../Helpers/ValidationHelpers.js";
+import { Button } from "../Documents/Button.js";
+import { DropdownChip, DropdownMedia, DropdownOption, DropdownTag, hasIcon } from "./DropdownParts.js";
+import { Field } from "./Field.js";
+import { useInputField } from "./InputField.js";
+import { useReadOnlyNotice } from "./ReadOnlyNotice.js";
+/** Rows a local list renders at first, and adds each time it scrolls near its end, so 10,000 options open at once. */
+const RENDER_STEP = 100;
+/** Closer to the end of the list than this, in pixels, renders or loads more. */
+const NEAR_END = 160;
+/** How long typing pauses before a server search starts, in milliseconds. */
+const SEARCH_DELAY = 250;
+/** Letters typed within this time, in milliseconds, add up to one search in a list without a search box. */
+const TYPEAHEAD_DELAY = 600;
+/** The tallest the list's panel grows, in pixels. */
+const PANEL_MAX_HEIGHT = 360;
+const PAGE_STEP = 10;
+/** Values named in the screen reader's "Selected: …" text and the "+12 more" chip's tooltip before "and N more". */
+const NAMES_LISTED = 20;
+const SKELETON_WIDTHS = ["72%", "54%", "64%", "46%"];
+const IDLE_LIST = { search: "", loadKey: undefined, items: [], page: 0, hasMore: false, total: undefined, status: "idle", errorPage: 1, firstKeys: new Set() };
+export function Dropdown(props) {
+    const { label, hint, error, design = "standard", size = "md", icon, options, loadOptions, loadKey, pageSize = 50, selectedOptions, resolveOptions, valueKey = "value", labelKey = "label", descriptionKey = "description", iconKey = "icon", columns, searchKeys, isOptionDisabled = isDisabledItem, isOptionInactive = isInactiveItem, searchable: searchableProp, clearable = true, loading = false, emptyMessage = "No options", renderValue, panelWidth, readOnlyMessage, fieldName, validateOn, className, inputClassName, style, required, validate, name, form, placeholder, disabled, readOnly, ref, onBlur, onFocus, onKeyDown, onClick, onInvalid, multiple: multipleProp, value: valueProp, defaultValue, onValueChange, min, max, selectAll = true, maxChips = 10, ...inputProps } = props;
+    const multiple = multipleProp === true;
+    const controlled = valueProp !== undefined;
+    const editable = !disabled && !readOnly;
+    const searchable = searchableProp ?? (Boolean(loadOptions) || (options?.length ?? 0) > 8);
+    const messageName = fieldName ?? (typeof label === "string" ? label : DEFAULT_FIELD_NAME);
+    // Values
+    const [ownValues, setOwnValues] = useState(() => toValueList(defaultValue, multiple));
+    const values = controlled ? toValueList(valueProp, multiple) : ownValues;
+    const valuesKey = values.map(optionKey).join("\n");
+    const valuesRef = useRef(values);
+    valuesRef.current = values;
+    const selectedKeys = useMemo(() => new Set(values.map(optionKey)), [valuesKey]);
+    const editedRef = useRef(false);
+    // Items: the options, pages from the server and items resolved for values (both kept by key), and selectedOptions.
+    const optionIndex = useMemo(() => (options ? indexItems(options, valueKey) : null), [options, valueKey]);
+    const selectedIndex = useMemo(() => (selectedOptions ? indexItems(selectedOptions, valueKey) : null), [selectedOptions, valueKey]);
+    const knownRef = useRef(new Map());
+    const findItem = (key) => optionIndex?.get(key) ?? knownRef.current.get(key) ?? selectedIndex?.get(key) ?? null;
+    const labelOf = (item) => itemLabel(item, labelKey, valueKey);
+    const listId = `${useId()}-list`;
+    const selectionId = `${listId}-selection`;
+    const panelRef = useRef(null);
+    const listRef = useRef(null);
+    /** Places the open panel against the box; null while closed. */
+    const placeRef = useRef(null);
+    const mountedRef = useRef(true);
+    const [open, setOpen] = useState(false);
+    const [search, setSearch] = useState("");
+    const [active, setActive] = useState(-1);
+    const [renderLimit, setRenderLimit] = useState(RENDER_STEP);
+    const [pinned, setPinned] = useState([]);
+    const scrollToActiveRef = useRef(false);
+    const typeaheadRef = useRef({ text: "", time: 0, pending: "" });
+    const field = useInputField({
+        ...props,
+        "aria-describedby": cx(props["aria-describedby"], selectionId),
+        onChange: handleSearchChange,
+    }, {
+        check: (_input, fieldName) => validateSelection(valuesRef.current, { required, min, max, validate }, fieldName),
+        checkKeys: [valuesKey, required, min, max, validate],
+        onReset: () => {
+            // Back to the values the field started with. A controlled dropdown is reset by its owner.
+            editedRef.current = false;
+            if (controlled)
+                return;
+            const initial = toValueList(defaultValue, multiple);
+            valuesRef.current = initial;
+            setOwnValues(initial);
+        },
+    });
+    const readOnlyNotice = useReadOnlyNotice(Boolean(readOnly) && !disabled, field.elementRef, readOnlyMessage ?? (multiple ? "Read-only: these choices cannot be changed." : "Read-only: this choice cannot be changed."), {
+        keys: ["ArrowDown", "ArrowUp"],
+    });
+    // A default value that arrives after mount (from an API, say) replaces the value, until the user changes it.
+    const defaultKey = toValueList(defaultValue, multiple).map(optionKey).join("\n");
+    useLayoutEffect(() => {
+        if (controlled || editedRef.current)
+            return;
+        const initial = toValueList(defaultValue, multiple);
+        if (initial.map(optionKey).join("\n") === valuesRef.current.map(optionKey).join("\n"))
+            return;
+        valuesRef.current = initial;
+        setOwnValues(initial);
+    }, [defaultKey]);
+    // Resolving values that nothing describes yet, once per value.
+    const requestedRef = useRef(new Set());
+    const pendingRef = useRef(new Set());
+    const [, setResolved] = useState(0);
+    useEffect(() => {
+        if (!resolveOptions || loading)
+            return;
+        const missing = valuesRef.current.filter(value => {
+            const key = optionKey(value);
+            return !findItem(key) && !requestedRef.current.has(key);
+        });
+        if (missing.length === 0)
+            return;
+        const keys = missing.map(optionKey);
+        for (const key of keys) {
+            requestedRef.current.add(key);
+            pendingRef.current.add(key);
+        }
+        setResolved(count => count + 1);
+        Promise.resolve()
+            .then(() => resolveOptions(missing))
+            .then(items => {
+            for (const item of items ?? []) {
+                const key = optionKey(itemValue(item, valueKey));
+                if (key)
+                    knownRef.current.set(key, item);
+            }
+        }, () => undefined)
+            .finally(() => {
+            for (const key of keys)
+                pendingRef.current.delete(key);
+            if (mountedRef.current)
+                setResolved(count => count + 1);
+        });
+    });
+    // Server pages
+    const [server, setServer] = useState(IDLE_LIST);
+    const [query, setQuery] = useState("");
+    const requestRef = useRef({ id: 0, controller: null });
+    const loadRef = useRef(loadOptions);
+    useLayoutEffect(() => {
+        loadRef.current = loadOptions;
+    });
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+            requestRef.current.controller?.abort();
+        };
+    }, []);
+    function loadPage(searchText, page) {
+        const load = loadRef.current;
+        if (!load)
+            return;
+        requestRef.current.controller?.abort();
+        const controller = new AbortController();
+        const id = ++requestRef.current.id;
+        requestRef.current.controller = controller;
+        const key = loadKey;
+        setServer(list => (page === 1 ? { ...list, search: searchText, loadKey: key, status: "loading" } : { ...list, status: "more" }));
+        Promise.resolve()
+            .then(() => load({ search: searchText, page, pageSize, skip: (page - 1) * pageSize, signal: controller.signal }))
+            .then(result => {
+            if (id !== requestRef.current.id || !mountedRef.current)
+                return;
+            const items = [...(result?.items ?? [])];
+            for (const item of items) {
+                const itemKey = optionKey(itemValue(item, valueKey));
+                if (itemKey)
+                    knownRef.current.set(itemKey, item);
+            }
+            const firstKeys = page === 1 ? new Set(items.map(item => optionKey(itemValue(item, valueKey)))) : null;
+            setServer(list => ({
+                search: searchText,
+                loadKey: key,
+                items: page === 1 ? items : appendNew(list.items, items, valueKey),
+                page,
+                hasMore: result?.hasMore ?? items.length >= pageSize,
+                total: result?.total,
+                status: "ready",
+                errorPage: 1,
+                firstKeys: firstKeys ?? list.firstKeys,
+            }));
+            // A fresh first page decides again which current values the list already shows.
+            if (firstKeys)
+                setPinned(pinnedValues(valuesRef.current, firstKeys));
+        }, () => {
+            if (id !== requestRef.current.id || !mountedRef.current || controller.signal.aborted)
+                return;
+            setServer(list => ({ ...list, status: "error", errorPage: page }));
+        });
+    }
+    function loadMore() {
+        if (loadOptions && server.status === "ready" && server.hasMore)
+            loadPage(server.search, server.page + 1);
+    }
+    // A new loadKey drops what was loaded for the old one.
+    const loadKeyRef = useRef(loadKey);
+    useEffect(() => {
+        if (Object.is(loadKeyRef.current, loadKey))
+            return;
+        loadKeyRef.current = loadKey;
+        requestRef.current.controller?.abort();
+        requestRef.current.id++;
+        setServer(IDLE_LIST);
+    }, [loadKey]);
+    // The server search follows typing after a pause.
+    useEffect(() => {
+        if (!loadOptions)
+            return;
+        const next = search.trim();
+        if (next === query)
+            return;
+        const timer = setTimeout(() => setQuery(next), next ? SEARCH_DELAY : 0);
+        return () => clearTimeout(timer);
+    }, [search]);
+    // An open list loads the first page of its search, unless it has it or is loading it.
+    useEffect(() => {
+        if (!open || !loadOptions)
+            return;
+        const current = (server.status === "ready" || server.status === "loading" || server.status === "more") && server.search === query && Object.is(server.loadKey, loadKey);
+        if (!current)
+            loadPage(query, 1);
+    }, [open, query, loadKey]);
+    /**
+     * Current values that show at the top of the list: values nothing describes, inactive items, and items the options
+     * do not hold (for a server list: not on the first page of the search).
+     */
+    function pinnedValues(current, firstKeys) {
+        return current.filter(value => {
+            const key = optionKey(value);
+            const item = findItem(key);
+            if (!item || isOptionInactive(item))
+                return true;
+            return loadOptions ? !firstKeys.has(key) : !optionIndex?.has(key);
+        });
+    }
+    function stateOf(key, item) {
+        // A server list may hold a bare value on a page not loaded yet: it is "Not found" only once resolveOptions did not return it.
+        if (!item)
+            return loadOptions && !(resolveOptions && requestedRef.current.has(key)) ? null : "unknown";
+        if (isOptionInactive(item))
+            return "inactive";
+        if (!loadOptions && !loading && !optionIndex?.has(key))
+            return "unavailable";
+        return null;
+    }
+    // A value resolveOptions has yet to look up counts as pending from the first render (the server's HTML too), so its
+    // bare id never flashes before the lookup starts.
+    const isPending = (key, item) => !item && (pendingRef.current.has(key) || loading || (Boolean(resolveOptions) && !requestedRef.current.has(key)));
+    /** Whether a row's item can be chosen. A chosen row can always be removed. */
+    function canPick(key, item) {
+        if (!item || isOptionDisabled(item) || isOptionInactive(item))
+            return false;
+        return Boolean(loadOptions) || Boolean(optionIndex?.has(key));
+    }
+    // Rows, only while open
+    const deferredSearch = useDeferredValue(search);
+    const keysForSearch = useMemo(() => searchKeys ?? defaultSearchKeys(labelKey, descriptionKey, valueKey, columns), [searchKeys, labelKey, descriptionKey, valueKey, columns]);
+    const words = useMemo(() => searchWords(deferredSearch), [deferredSearch]);
+    const localMatches = useMemo(() => (open && options && !loadOptions ? filterItems(options, deferredSearch, keysForSearch) : []), [open, options, Boolean(loadOptions), deferredSearch, keysForSearch]);
+    const sourceItems = loadOptions ? server.items : localMatches;
+    const offered = useMemo(() => {
+        if (!open)
+            return [];
+        const seen = new Set();
+        return sourceItems.filter(item => {
+            const key = optionKey(itemValue(item, valueKey));
+            if (!key || seen.has(key) || isOptionInactive(item))
+                return false;
+            seen.add(key);
+            return true;
+        });
+    }, [open, sourceItems, valueKey, isOptionInactive]);
+    const atMax = multiple && max !== undefined && values.length >= max;
+    const rows = [];
+    if (open) {
+        for (const value of pinned) {
+            const key = optionKey(value);
+            const item = findItem(key);
+            const matches = words.length === 0 || (item ? matchesSearch(item, words, keysForSearch) : words.every(word => foldSearchText(key).includes(word)));
+            if (matches)
+                rows.push({ key, value, item, pinned: true });
+        }
+        const limit = loadOptions ? offered.length : Math.min(offered.length, renderLimit);
+        for (let index = 0; index < limit; index++) {
+            const item = offered[index];
+            rows.push({ key: optionKey(itemValue(item, valueKey)), value: itemValue(item, valueKey), item, pinned: false });
+        }
+    }
+    const pinnedCount = rows.findIndex(row => !row.pinned) < 0 ? rows.length : rows.findIndex(row => !row.pinned);
+    const rowDisabled = (row) => !selectedKeys.has(row.key) && (!canPick(row.key, row.item) || atMax);
+    const firstEnabled = (from, direction) => {
+        for (let index = from; index >= 0 && index < rows.length; index += direction)
+            if (!rowDisabled(rows[index]))
+                return index;
+        return -1;
+    };
+    // Without a move of its own, the highlight rests on the chosen row (a single choice, before any search) or the first that can be picked.
+    const fallbackActive = () => {
+        if (!multiple && !deferredSearch.trim()) {
+            const chosen = rows.findIndex(row => selectedKeys.has(row.key));
+            if (chosen >= 0)
+                return chosen;
+        }
+        return firstEnabled(0, 1);
+    };
+    const activeIndex = !open ? -1 : active >= 0 && active < rows.length ? active : fallbackActive();
+    const staleRows = Boolean(loadOptions) && server.status === "loading" && server.items.length > 0;
+    // An open server list that has not started its first request yet is loading too: its placeholder rows already show.
+    const busy = loading || pendingRef.current.size > 0 || (Boolean(loadOptions) && (server.status === "loading" || server.status === "more" || (open && server.status === "idle")));
+    // Select all and Clear act on every option the list holds for the search, rendered yet or not, and on the current
+    // values shown at its top. The options are split once per list and selection, not on every highlight move.
+    const showBulk = open && multiple && selectAll;
+    const offeredSplit = useMemo(() => {
+        if (!showBulk)
+            return null;
+        const keys = new Set();
+        const addable = [];
+        const chosen = [];
+        for (const item of offered) {
+            const value = itemValue(item, valueKey);
+            const key = optionKey(value);
+            keys.add(key);
+            if (selectedKeys.has(key))
+                chosen.push(key);
+            else if (!isOptionDisabled(item))
+                addable.push(value);
+        }
+        return { keys, addable, chosen };
+    }, [showBulk, offered, selectedKeys, valueKey, isOptionDisabled]);
+    let bulk = null;
+    if (offeredSplit) {
+        const addable = [...offeredSplit.addable];
+        const chosen = [...offeredSplit.chosen];
+        for (const row of rows.slice(0, pinnedCount)) {
+            if (offeredSplit.keys.has(row.key))
+                continue;
+            if (selectedKeys.has(row.key))
+                chosen.push(row.key);
+            else if (canPick(row.key, row.item))
+                addable.push(row.value);
+        }
+        bulk = { addable, chosen };
+    }
+    function commit(next) {
+        editedRef.current = true;
+        valuesRef.current = next;
+        if (!controlled)
+            setOwnValues(next);
+        field.change();
+        if (multiple) {
+            onValueChange?.(next, next.map(value => findItem(optionKey(value))));
+        }
+        else {
+            const value = next[0] ?? null;
+            onValueChange?.(value, value === null ? null : findItem(optionKey(value)));
+        }
+    }
+    function openPanel() {
+        if (!editable || open)
+            return;
+        field.elementRef.current?.focus();
+        // Shown before its rows render, so the list can scroll to the chosen row as it mounts. Nothing paints in between.
+        const panel = panelRef.current;
+        if (panel && !isPopoverOpen(panel))
+            panel.showPopover();
+        setPinned(pinnedValues(valuesRef.current, server.firstKeys));
+        // A single choice far down a long list is rendered, so the list can open on it.
+        const chosenKey = !multiple && !loadOptions && options && valuesRef.current.length > 0 ? optionKey(valuesRef.current[0]) : null;
+        const chosenIndex = chosenKey === null ? -1 : options.findIndex(item => optionKey(itemValue(item, valueKey)) === chosenKey);
+        setRenderLimit(chosenIndex < RENDER_STEP ? RENDER_STEP : (Math.ceil((chosenIndex + 1) / RENDER_STEP) + 1) * RENDER_STEP);
+        setActive(-1);
+        setOpen(true);
+    }
+    /** Closes the list and drops the typed search. With `returnFocus`, focus inside the panel goes back to the box. */
+    function closePanel(returnFocus = false) {
+        const panel = panelRef.current;
+        const input = field.elementRef.current;
+        const focusInPanel = Boolean(panel?.contains(document.activeElement));
+        if (isPopoverOpen(panel))
+            panel.hidePopover();
+        setOpen(false);
+        setActive(-1);
+        if (input && input.value)
+            input.value = "";
+        setSearch("");
+        if (returnFocus && focusInPanel)
+            input?.focus();
+    }
+    function pick(row) {
+        const chosen = selectedKeys.has(row.key);
+        if (!chosen && rowDisabled(row))
+            return;
+        if (multiple) {
+            commit(chosen ? valuesRef.current.filter(value => optionKey(value) !== row.key) : [...valuesRef.current, row.value]);
+            return;
+        }
+        if (!chosen)
+            commit([row.value]);
+        closePanel(true);
+    }
+    function remove(key) {
+        commit(valuesRef.current.filter(value => optionKey(value) !== key));
+    }
+    function clear() {
+        commit([]);
+        field.elementRef.current?.focus();
+    }
+    /** Adds every option the list shows that is not chosen yet, after the values already chosen. */
+    function selectShown() {
+        if (!bulk)
+            return;
+        const current = new Set(valuesRef.current.map(optionKey));
+        commit([...valuesRef.current, ...bulk.addable.filter(value => !current.has(optionKey(value)))]);
+    }
+    /** Removes the chosen values the list shows. Values a search hides stay. */
+    function clearShown() {
+        if (!bulk)
+            return;
+        const shown = new Set(bulk.chosen);
+        commit(valuesRef.current.filter(value => !shown.has(optionKey(value))));
+    }
+    function handleSearchChange(event) {
+        const input = event.currentTarget;
+        // Without a search box, typed letters jump to an option (see the key handler) and never stay in the box.
+        if (!searchable) {
+            input.value = "";
+            return;
+        }
+        setSearch(input.value);
+        setActive(-1);
+        setRenderLimit(RENDER_STEP);
+        if (!open)
+            openPanel();
+    }
+    /** Moves the highlight by `delta` rows (±Infinity: the first or last), past rows that cannot be picked. */
+    function moveActive(delta) {
+        if (rows.length === 0)
+            return;
+        let target;
+        if (delta === Infinity)
+            target = firstEnabled(rows.length - 1, -1);
+        else if (delta === -Infinity)
+            target = firstEnabled(0, 1);
+        else {
+            const direction = delta > 0 ? 1 : -1;
+            const from = activeIndex < 0 ? (direction > 0 ? 0 : rows.length - 1) : Math.max(0, Math.min(rows.length - 1, activeIndex + delta));
+            target = firstEnabled(from, direction);
+            // A page jump past the last row that can be picked stops on it.
+            if (target < 0 && Math.abs(delta) > 1)
+                target = firstEnabled(from, direction > 0 ? -1 : 1);
+        }
+        if (target < 0)
+            return;
+        scrollToActiveRef.current = true;
+        setActive(target);
+        if (target >= rows.length - 5) {
+            if (loadOptions)
+                loadMore();
+            else if (renderLimit < offered.length)
+                setRenderLimit(limit => limit + RENDER_STEP);
+        }
+    }
+    /** Arrow keys, Page Up and Down, Home and End, and Enter in an open list. Returns whether the key was used. */
+    function navigate(event) {
+        const { key } = event;
+        const input = field.elementRef.current;
+        const caretKeys = searchable && Boolean(input?.value);
+        switch (key) {
+            case "ArrowDown":
+                moveActive(1);
+                return true;
+            case "ArrowUp":
+                moveActive(-1);
+                return true;
+            case "PageDown":
+                moveActive(PAGE_STEP);
+                return true;
+            case "PageUp":
+                moveActive(-PAGE_STEP);
+                return true;
+            case "Home":
+            case "End":
+                // In typed text these move the caret.
+                if (caretKeys)
+                    return false;
+                moveActive(key === "End" ? Infinity : -Infinity);
+                return true;
+            case "Enter": {
+                const row = rows[activeIndex];
+                if (row && !staleRows)
+                    pick(row);
+                return true;
+            }
+            default:
+                return false;
+        }
+    }
+    function handleKeyDown(event) {
+        readOnlyNotice.onKeyDown(event);
+        const { key } = event;
+        const input = event.currentTarget;
+        if (editable) {
+            if (open && navigate(event)) {
+                event.preventDefault();
+            }
+            else if (!open && (key === "ArrowDown" || key === "ArrowUp")) {
+                event.preventDefault();
+                openPanel();
+            }
+            else if (key === "Escape" && open) {
+                // Closes the list only: the page (a dialog, say) does not see this Esc.
+                event.preventDefault();
+                event.stopPropagation();
+                closePanel();
+            }
+            else if (key === "Escape" && input.value) {
+                event.preventDefault();
+                event.stopPropagation();
+                input.value = "";
+                setSearch("");
+            }
+            else if (key === "Tab" && open) {
+                closePanel();
+            }
+            else if (key === "Backspace" && !input.value && values.length > 0 && (multiple || clearable)) {
+                // An empty search box: Backspace removes the last chip, or the single value.
+                commit(valuesRef.current.slice(0, -1));
+            }
+            else if (!searchable && (key === " " || key === "Enter") && !open) {
+                event.preventDefault();
+                openPanel();
+            }
+            else if (!searchable && key === " " && open) {
+                event.preventDefault();
+                const row = rows[activeIndex];
+                if (row)
+                    pick(row);
+            }
+            else if (!searchable && key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
+                event.preventDefault();
+                typeahead(key);
+            }
+        }
+        onKeyDown?.(event);
+    }
+    /** Jumps to the next option whose label starts with the letters typed in quick succession. */
+    function typeahead(char) {
+        const state = typeaheadRef.current;
+        const now = Date.now();
+        state.text = now - state.time > TYPEAHEAD_DELAY ? char : state.text + char;
+        state.time = now;
+        state.pending = state.text;
+        if (!open)
+            openPanel();
+        else
+            applyTypeahead();
+    }
+    function applyTypeahead() {
+        const state = typeaheadRef.current;
+        const typed = foldSearchText(state.pending);
+        state.pending = "";
+        if (!typed || rows.length === 0)
+            return;
+        // The same letter pressed again ("s", "s") cycles through the options that start with it, as in a native select.
+        const text = [...typed].every(char => char === typed[0]) ? typed[0] : typed;
+        // One letter again moves on to the next option with it; more letters keep the current one while it still matches.
+        // Before any move, "current" is the chosen row, or nothing, so the first letter finds the first match.
+        const current = active >= 0 && active < rows.length ? active : rows.findIndex(row => selectedKeys.has(row.key));
+        const start = text.length === 1 ? current + 1 : Math.max(current, 0);
+        for (let step = 0; step < rows.length; step++) {
+            const index = (start + step) % rows.length;
+            const row = rows[index];
+            if (rowDisabled(row))
+                continue;
+            if (foldSearchText(row.item ? labelOf(row.item) : row.key).startsWith(text)) {
+                scrollToActiveRef.current = true;
+                setActive(index);
+                return;
+            }
+        }
+    }
+    function handleClick(event) {
+        if (!open)
+            openPanel();
+        readOnlyNotice.onClick(event);
+        onClick?.(event);
+    }
+    function handleBlur(event) {
+        // Focus moving anywhere but the panel closes it.
+        if (open && !(event.relatedTarget instanceof Node && panelRef.current?.contains(event.relatedTarget)))
+            closePanel();
+        readOnlyNotice.hide();
+        field.controlProps.onBlur(event);
+    }
+    // A press on the chips or the space around the text focuses the box and opens the list, like a native select.
+    function handleControlMouseDown(event) {
+        if (disabled)
+            return;
+        const target = event.target;
+        const input = field.elementRef.current;
+        if (target === input || target.closest(".nx-dropdown-chip__remove"))
+            return;
+        event.preventDefault();
+        input?.focus();
+        if (readOnly)
+            readOnlyNotice.show(input);
+        else if (!open)
+            openPanel();
+    }
+    // Focus leaving the panel for anything but the box (after dragging the list's scroll bar) closes it.
+    function handlePanelBlur(event) {
+        const next = event.relatedTarget;
+        if (next instanceof Node && (event.currentTarget.contains(next) || next === field.elementRef.current))
+            return;
+        closePanel();
+    }
+    function handlePanelKeyDown(event) {
+        if (event.target === field.elementRef.current)
+            return;
+        if (event.key === "Escape") {
+            event.preventDefault();
+            event.stopPropagation();
+            closePanel(true);
+        }
+        else if (navigate(event)) {
+            // Focus is on the list after a press on its scroll bar: keys work there too, and focus goes back to the box.
+            event.preventDefault();
+            field.elementRef.current?.focus();
+        }
+    }
+    const rowIndexOf = (target) => {
+        const row = target instanceof Element ? target.closest("[data-index]") : null;
+        return row ? Number(row.getAttribute("data-index")) : -1;
+    };
+    function handleListPointerMove(event) {
+        const index = rowIndexOf(event.target);
+        const row = rows[index];
+        if (row && index !== active && !rowDisabled(row))
+            setActive(index);
+    }
+    function handleListClick(event) {
+        const row = rows[rowIndexOf(event.target)];
+        if (row && !staleRows)
+            pick(row);
+    }
+    function handleListScroll(event) {
+        const list = event.currentTarget;
+        if (list.scrollHeight - list.scrollTop - list.clientHeight > NEAR_END)
+            return;
+        if (loadOptions)
+            loadMore();
+        else if (renderLimit < offered.length)
+            setRenderLimit(limit => limit + RENDER_STEP);
+    }
+    function retry() {
+        loadPage(server.search, server.errorPage);
+    }
+    // The panel is a manual popover under the box (above it when there is more room there), at least as wide as the box.
+    // It closes only through this component, so the state always matches the screen.
+    useLayoutEffect(() => {
+        const panel = panelRef.current;
+        const box = field.elementRef.current?.closest(".nx-field__box");
+        if (!open || !panel || !box)
+            return;
+        if (!isPopoverOpen(panel))
+            panel.showPopover();
+        let side;
+        const place = () => {
+            side = placeListPanel(panel, box.getBoundingClientRect(), { side, maxHeight: PANEL_MAX_HEIGHT });
+        };
+        place();
+        const list = listRef.current;
+        // The width the browser keeps for a scroll bar (0 where scroll bars float over the content): the list's CSS takes it
+        // off its right padding.
+        if (list)
+            panel.style.setProperty("--nx-dropdown-gutter", `${list.offsetWidth - list.clientWidth}px`);
+        // A single choice opens with its row in the middle of the list.
+        const chosen = !multiple && list?.querySelector('[role="option"][aria-selected="true"]');
+        if (list && chosen)
+            list.scrollTop = chosen.offsetTop - (list.clientHeight - chosen.offsetHeight) / 2;
+        const stopFollowing = followAnchor(place);
+        placeRef.current = place;
+        // Sizes that change outside a render (an image loading in a row, say): place again in the next frame.
+        let frame = 0;
+        const resize = new ResizeObserver(() => {
+            cancelAnimationFrame(frame);
+            frame = requestAnimationFrame(place);
+        });
+        resize.observe(panel);
+        resize.observe(box);
+        const onPointerDown = (event) => {
+            const target = event.target;
+            if (!panel.contains(target) && !box.contains(target))
+                closePanel();
+        };
+        document.addEventListener("pointerdown", onPointerDown, true);
+        return () => {
+            stopFollowing();
+            placeRef.current = null;
+            cancelAnimationFrame(frame);
+            resize.disconnect();
+            document.removeEventListener("pointerdown", onPointerDown, true);
+            if (isPopoverOpen(panel))
+                panel.hidePopover();
+        };
+    }, [open]);
+    // Rows arriving, and chips wrapping in the box after a pick, change the sizes in a render: placing again before the
+    // browser paints keeps the panel from showing for a frame over the grown box, or past the window's edge.
+    useLayoutEffect(() => {
+        placeRef.current?.();
+    });
+    // After a keyboard move, the highlighted row scrolls into view below the column headings. Letters typed while the
+    // list was closed find their option once its rows exist.
+    useLayoutEffect(() => {
+        if (!open)
+            return;
+        if (typeaheadRef.current.pending)
+            applyTypeahead();
+        const list = listRef.current;
+        if (!scrollToActiveRef.current || !list)
+            return;
+        scrollToActiveRef.current = false;
+        const row = list.querySelector(`[data-index="${activeIndex}"]`);
+        if (!row)
+            return;
+        const header = list.querySelector(".nx-dropdown-list__header");
+        const style = getComputedStyle(list);
+        const top = row.offsetTop - (header ? header.offsetHeight + 4 : parseFloat(style.paddingTop));
+        const bottom = row.offsetTop + row.offsetHeight + parseFloat(style.paddingBottom) - list.clientHeight;
+        if (list.scrollTop > top)
+            list.scrollTop = top;
+        else if (list.scrollTop < bottom)
+            list.scrollTop = bottom;
+    });
+    // A short server page leaves no scroll bar to reach the end with: load on until the list can scroll.
+    useEffect(() => {
+        const list = listRef.current;
+        if (open && list && server.status === "ready" && server.hasMore && list.scrollHeight - list.clientHeight <= NEAR_END)
+            loadMore();
+    }, [open, server]);
+    // The box
+    const mediaFor = (item) => _jsx(DropdownMedia, { item: item, label: labelOf(item), columns: columns, iconKey: iconKey });
+    // The names of values in a sentence: up to NAMES_LISTED, then how many more, so thousands of values stay one short line.
+    const namesOf = (list) => {
+        const names = list.slice(0, NAMES_LISTED).map(value => {
+            const item = findItem(optionKey(value));
+            return item ? labelOf(item) : optionKey(value);
+        });
+        return list.length > NAMES_LISTED ? `${names.join(", ")}, and ${formatCount(list.length - NAMES_LISTED)} more` : names.join(", ");
+    };
+    let boxContent;
+    if (multiple) {
+        // Past maxChips, one chip counts the rest: a long selection (Select all, say) keeps the box small.
+        const chipValues = values.length > Math.max(0, maxChips) ? values.slice(0, Math.max(0, maxChips)) : values;
+        const moreValues = values.slice(chipValues.length);
+        boxContent = (_jsxs(_Fragment, { children: [chipValues.map(value => {
+                    const key = optionKey(value);
+                    const item = findItem(key);
+                    return (_jsx(DropdownChip, { label: item ? labelOf(item) : key, media: item ? mediaFor(item) : null, state: isPending(key, item) ? null : stateOf(key, item), pending: isPending(key, item), onRemove: editable ? () => remove(key) : undefined }, key));
+                }), moreValues.length > 0 && (_jsx("span", { className: "nx-dropdown-chip nx-dropdown-chip--more", title: namesOf(moreValues), children: chipValues.length > 0 ? `+${formatCount(moreValues.length)} more` : `${formatCount(values.length)} selected` }))] }));
+    }
+    else if (values.length > 0) {
+        const key = optionKey(values[0]);
+        const item = findItem(key);
+        const pending = isPending(key, item);
+        boxContent = (_jsxs("span", { className: "nx-dropdown__value", "aria-hidden": "true", children: [item && renderValue ? (renderValue(item)) : (_jsxs(_Fragment, { children: [item && mediaFor(item), _jsx("span", { className: "nx-dropdown__value-text", children: pending ? _jsx("span", { className: "nx-dropdown-skeleton" }) : item ? labelOf(item) : key })] })), !pending && _jsx(DropdownTag, { state: stateOf(key, item) })] }));
+    }
+    const showClear = clearable && editable && values.length > 0;
+    // The list
+    let listContent = null;
+    let footer = null;
+    if (open) {
+        const typedColumns = columns;
+        const tagColumn = typedColumns ? tagColumnOf(typedColumns, labelKey) : -1;
+        const iconSlot = !typedColumns && rows.some(row => row.item && hasIcon(readField(row.item, iconKey)));
+        const showHeader = typedColumns?.some(column => column.header);
+        const skeleton = rows.length === 0 && ((Boolean(loadOptions) && (server.status === "idle" || server.status === "loading")) || (!loadOptions && loading));
+        const failed = Boolean(loadOptions) && server.status === "error";
+        const empty = rows.length === 0 && !skeleton && !failed;
+        const typed = deferredSearch.trim();
+        listContent = (_jsxs(_Fragment, { children: [showHeader && (_jsxs("div", { className: "nx-dropdown-list__header", "aria-hidden": "true", children: [_jsx("span", {}), typedColumns.map((column, index) => (_jsx("span", { className: "nx-dropdown-list__heading", style: column.align && column.align !== "start" ? { justifySelf: column.align, textAlign: column.align } : undefined, children: column.header }, index)))] })), rows.map((row, index) => {
+                    const labelField = row.item ? readField(row.item, labelKey) : undefined;
+                    const description = row.item && !typedColumns ? readField(row.item, descriptionKey) : undefined;
+                    const pending = isPending(row.key, row.item);
+                    return (_jsx(RowGroup, { heading: index === 0 && pinnedCount > 0 && pinnedCount < rows.length ? "Selected" : undefined, separator: row.pinned === false && index === pinnedCount && pinnedCount > 0, children: _jsx(DropdownOption, { id: `${listId}-${index}`, index: index, item: row.item, label: row.item ? labelOf(row.item) : row.key, labelNode: isValidElement(labelField) ? labelField : undefined, description: typeof description === "string" || typeof description === "number" || isValidElement(description) ? description : undefined, columns: typedColumns, tagColumn: tagColumn, iconKey: iconKey, iconSlot: iconSlot, multiple: multiple, selected: selectedKeys.has(row.key), active: index === activeIndex, disabled: rowDisabled(row), pending: pending, state: row.pinned && !pending ? stateOf(row.key, row.item) : null }) }, `${row.pinned ? "p" : "o"}-${row.key}`));
+                }), skeleton &&
+                    SKELETON_WIDTHS.map((width, index) => (_jsxs("div", { className: "nx-dropdown-option nx-dropdown-option--skeleton", "aria-hidden": "true", children: [_jsx("span", { className: "nx-dropdown-option__check" }), typedColumns ? (typedColumns.map((column, columnIndex) => (_jsx("span", { className: cx("nx-dropdown-skeleton", (column.type === "avatar" || column.type === "image" || column.type === "icon") && `nx-dropdown-skeleton--${column.type}`), style: column.type === "avatar" || column.type === "image" || column.type === "icon" ? undefined : { width } }, columnIndex)))) : (_jsx("span", { className: "nx-dropdown-skeleton", style: { width } }))] }, `skeleton-${index}`))), server.status === "more" && (_jsxs("div", { className: "nx-dropdown-list__status", children: [_jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }), _jsx("span", { children: "Loading more\u2026" })] })), failed && (_jsxs("div", { className: "nx-dropdown-list__status nx-dropdown-list__status--error", role: "alert", children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: server.errorPage > 1 ? "Could not load more options." : "Could not load the options." }), _jsx(Button, { size: "sm", variant: "secondary", onClick: retry, children: "Retry" })] })), empty && _jsx("div", { className: "nx-dropdown-list__status", children: typed ? `No matches for "${typed}"` : emptyMessage })] }));
+        const shownCount = loadOptions && server.total !== undefined && server.status !== "loading" ? `${formatCount(server.items.length)} of ${formatCount(server.total)} shown` : null;
+        const counts = [];
+        if (multiple)
+            counts.push(max !== undefined ? `${values.length} of ${max} selected` : `${values.length} selected`);
+        // With Select all, its label says how many rows a server list has loaded ("Select 30 shown"), and the total moves to its tooltip.
+        if (shownCount && !bulk)
+            counts.push(shownCount);
+        const count = (_jsx("span", { className: "nx-dropdown-panel__count", "aria-live": "polite", children: counts.join(" · ") }));
+        const done = multiple && (_jsx(Button, { size: "sm", variant: "primary", onClick: () => closePanel(true), children: "Done" }));
+        if (bulk) {
+            // One footer: Select all and Clear on the left, the count and Done on the right. Rows that are about to change
+            // (a new search loading, placeholders) take no bulk action.
+            const settled = !skeleton && !staleRows && !(loading && !loadOptions);
+            const overMax = max !== undefined && values.length + bulk.addable.length > max;
+            const partial = Boolean(loadOptions) && server.hasMore;
+            const selectNote = [overMax && bulk.addable.length > 0 ? `Up to ${max} can be selected.` : "", partial && shownCount ? `${shownCount}: scroll the list to load more.` : ""].filter(Boolean).join(" ");
+            footer = (_jsxs("div", { className: "nx-dropdown-panel__foot nx-dropdown-panel__foot--actions", children: [_jsxs("div", { className: "nx-dropdown-panel__actions", children: [_jsx(Button, { size: "sm", variant: "ghost", hoverTone: "primary", disabled: !settled || bulk.addable.length === 0 || overMax, title: selectNote || undefined, onClick: selectShown, children: partial ? `Select ${formatCount(rows.length)} shown` : "Select all" }), _jsx(Button, { size: "sm", variant: "ghost", hoverTone: "primary", disabled: !settled || bulk.chosen.length === 0, onClick: clearShown, children: "Clear" })] }), _jsxs("div", { className: "nx-dropdown-panel__end", children: [count, done] })] }));
+        }
+        else if (multiple || counts.length > 0) {
+            footer = (_jsxs("div", { className: "nx-dropdown-panel__foot", children: [count, done] }));
+        }
+    }
+    // The check column, the columns, and an empty last track whose gap keeps text off the row's end.
+    const gridColumns = columns ? `auto ${columns.map(column => columnTrack(column)).join(" ")} 0px` : undefined;
+    const panelStyle = panelWidth === undefined ? undefined : { width: typeof panelWidth === "number" ? `${panelWidth}px` : panelWidth };
+    return (_jsxs(_Fragment, { children: [_jsxs(Field, { controlId: field.controlId, messageId: field.messageId, label: label, required: required, design: design, size: size, hint: hint, error: field.error, icon: icon, actions: _jsxs(_Fragment, { children: [busy && (_jsx("span", { className: "nx-dropdown__spinner", title: "Loading", "aria-hidden": "true", children: _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }) })), showClear && (_jsx("button", { type: "button", className: "nx-field__action nx-dropdown__clear", tabIndex: -1, "aria-label": "Clear", title: "Clear", onMouseDown: event => event.preventDefault(), onClick: clear, children: _jsx(InlineIcon, { icon: iconX }) })), readOnlyNotice.lock, !readOnly && (_jsx("button", { type: "button", className: "nx-field__action nx-dropdown__toggle", tabIndex: -1, "aria-label": open ? "Close the list" : "Open the list", "aria-expanded": open, "aria-controls": open ? listId : undefined, disabled: disabled, onMouseDown: event => event.preventDefault(), onClick: () => (open ? closePanel() : openPanel()), children: _jsx(InlineIcon, { icon: iconChevronDown }) }))] }), disabled: disabled, readOnly: readOnly, raiseLabel: values.length > 0 || Boolean(placeholder), className: cx("nx-field--dropdown", className), style: style, children: [_jsxs("div", { className: cx("nx-dropdown__control", multiple ? "nx-dropdown__control--multiple" : "nx-dropdown__control--single"), "data-searchable": searchable || undefined, "data-has-value": values.length > 0 || undefined, onMouseDown: handleControlMouseDown, children: [boxContent, _jsx("input", { autoComplete: "off", spellCheck: false, ...inputProps, ...field.controlProps, type: "text", role: "combobox", "aria-expanded": open, "aria-haspopup": "listbox", "aria-controls": open ? listId : undefined, "aria-activedescendant": activeIndex >= 0 ? `${listId}-${activeIndex}` : undefined, "aria-autocomplete": searchable ? "list" : "none", inputMode: searchable ? inputProps.inputMode : "none", name: undefined, form: form, className: cx("nx-field__control", "nx-dropdown__input", inputClassName), placeholder: values.length > 0 ? " " : placeholder || " ", disabled: disabled, readOnly: readOnly, onBlur: handleBlur, onFocus: onFocus, onKeyDown: handleKeyDown, onClick: handleClick }), _jsx("span", { id: selectionId, className: "nx-visually-hidden", children: values.length > 0 ? `Selected: ${namesOf(values)}` : "" })] }), name &&
+                        (multiple ? (values.map(value => _jsx("input", { type: "hidden", name: name, form: form, disabled: disabled, value: optionKey(value) }, optionKey(value)))) : (_jsx("input", { type: "hidden", name: name, form: form, disabled: disabled, value: optionKey(values[0]) })))] }), readOnlyNotice.notice, !readOnly && (_jsx("div", { ref: panelRef, popover: "manual", className: cx("nx-popover", "nx-dropdown-panel", `nx-dropdown-panel--${size}`), style: panelStyle, onKeyDown: handlePanelKeyDown, onBlur: handlePanelBlur, 
+                // The box keeps focus while rows and buttons are pressed. A press on the list itself is left alone, so its
+                // scroll bar can be dragged.
+                onMouseDown: event => {
+                    if (event.target !== listRef.current)
+                        event.preventDefault();
+                }, children: open && (_jsxs(_Fragment, { children: [_jsx("div", { ref: listRef, id: listId, role: "listbox", "aria-label": messageName === DEFAULT_FIELD_NAME ? "Options" : messageName, "aria-multiselectable": multiple || undefined, "aria-busy": busy || undefined, tabIndex: -1, className: cx("nx-dropdown-list", columns && "nx-dropdown-list--columns"), style: gridColumns ? { gridTemplateColumns: gridColumns } : undefined, "data-stale": staleRows || undefined, onPointerMove: handleListPointerMove, onClick: handleListClick, onScroll: handleListScroll, children: listContent }), footer] })) }))] }));
+}
+/** A row, after the "Selected" heading when it opens the list, or after a line when it follows the selected rows. */
+function RowGroup({ heading, separator, children }) {
+    return (_jsxs(_Fragment, { children: [heading && (_jsx("div", { className: "nx-dropdown-list__group", role: "presentation", children: heading })), separator && _jsx("div", { className: "nx-dropdown-list__separator", role: "separator" }), children] }));
+}
+/** The column that carries a row's tag: the label's column, or else the last text column, or else the last. */
+function tagColumnOf(columns, labelKey) {
+    const labelColumn = columns.findIndex(column => column.key === labelKey);
+    if (labelColumn >= 0)
+        return labelColumn;
+    for (let index = columns.length - 1; index >= 0; index--) {
+        const type = columns[index].type ?? "text";
+        if (type === "text" || type === "muted" || type === "code")
+            return index;
+    }
+    return columns.length - 1;
+}
+const formatCount = (count) => count.toLocaleString("en-US");
+/** Items of a later page that earlier pages do not hold already, after them. Server data can shift between requests. */
+function appendNew(items, page, valueKey) {
+    const keys = new Set(items.map(item => optionKey(itemValue(item, valueKey))));
+    return [...items, ...page.filter(item => !keys.has(optionKey(itemValue(item, valueKey))))];
+}