@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/components/record-picker.js

@@ -0,0 +1,650 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Popover as PopoverPrimitive } from "radix-ui";
+import { Check, ChevronsUpDown, ExternalLink, LayoutList, Plus, RotateCw, Search, TriangleAlert, X } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { mergeIds } from "../lib/compose-refs.js";
+import { FieldContextReset, useFieldControl } from "../lib/field-context.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { SmartLink } from "../lib/provider.js";
+import { highlightParts, matchText } from "../lib/text.js";
+import { usePortalContainer } from "../lib/theme-scope.js";
+import { Layer } from "../lib/layer.js";
+import { ChipRemoveButton } from "../lib/islands.js";
+import { useControllableState, useLatest } from "../lib/use-controllable-state.js";
+import { controlVariants, itemSlots, itemVariants } from "../lib/variants.js";
+import { Avatar } from "./avatar.js";
+import { Button, IconButton } from "./button.js";
+import { Checkbox } from "./checkbox.js";
+import { Dialog, DialogBody, DialogContent, DialogFooter, DialogHeader } from "./dialog.js";
+import { Skeleton } from "./skeleton.js";
+import { Spinner } from "./spinner.js";
+/**
+ * A `RecordSource` over an in-memory array, searched with locale folding (İ/ı, accents).
+ * Good for small sets, tests and prototypes; switch to a server `search` later without
+ * touching the picker.
+ */
+export function arrayRecordSource(key, items, options) {
+    const { getKeywords, pageSize = 50, delay = 0, ...rest } = options;
+    const wait = (signal) => new Promise((resolve, reject) => {
+        if (!delay)
+            return resolve();
+        const timer = setTimeout(resolve, delay);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(new DOMException("Aborted", "AbortError"));
+        });
+    });
+    return {
+        key,
+        ...rest,
+        async search(query, { signal, cursor, locale }) {
+            await wait(signal);
+            const q = query.trim();
+            const all = q
+                ? items.filter((r) => matchText([rest.getLabel(r), rest.getDescription?.(r) ?? "", ...(getKeywords?.(r) ?? [])].join(" "), q, locale))
+                : items;
+            const start = cursor ? Number(cursor) : 0;
+            const end = start + pageSize;
+            return { items: all.slice(start, end), nextCursor: end < all.length ? String(end) : undefined };
+        },
+        async getByIds(ids, signal) {
+            await wait(signal);
+            const set = new Set(ids);
+            return items.filter((r) => set.has(rest.getId(r)));
+        },
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Session caches (per source key)                                     */
+/* ------------------------------------------------------------------ */
+const recordCache = new Map();
+const recentCache = new Map();
+const pageCache = new Map();
+const PAGE_TTL = 30_000;
+function remember(source, records) {
+    let m = recordCache.get(source.key);
+    if (!m)
+        recordCache.set(source.key, (m = new Map()));
+    for (const r of records)
+        m.set(source.getId(r), r);
+}
+function cached(source, id) {
+    return recordCache.get(source.key)?.get(id);
+}
+function pushRecent(source, ids) {
+    const prev = recentCache.get(source.key) ?? [];
+    recentCache.set(source.key, [...ids, ...prev.filter((x) => !ids.includes(x))].slice(0, 5));
+}
+/** Clears the picker's session caches (after a logout, or in tests). Pass a key to clear one collection. */
+export function clearRecordPickerCache(key) {
+    if (key === undefined) {
+        recordCache.clear();
+        recentCache.clear();
+        pageCache.clear();
+        return;
+    }
+    recordCache.delete(key);
+    recentCache.delete(key);
+    for (const k of pageCache.keys())
+        if (k.startsWith(`${key}\u0000`))
+            pageCache.delete(k);
+}
+const isAbort = (e) => e instanceof DOMException && e.name === "AbortError";
+/** Debounced, abortable, paged search against a source. */
+function useRecordSearch(source, query, enabled, locale) {
+    const sourceRef = useLatest(source);
+    const [state, setState] = React.useState({
+        items: [],
+        loading: false,
+        loadingMore: false,
+        error: null,
+        query: "",
+    });
+    const [attempt, setAttempt] = React.useState(0);
+    const ctrlRef = React.useRef(null);
+    React.useEffect(() => {
+        if (!enabled)
+            return;
+        const src = sourceRef.current;
+        const cacheKey = `${src.key}\u0000${query.trim()}`;
+        const hit = pageCache.get(cacheKey);
+        if (hit && Date.now() - hit.at < PAGE_TTL && attempt === 0) {
+            setState({ items: hit.items, nextCursor: hit.nextCursor, loading: false, loadingMore: false, error: null, query });
+            return;
+        }
+        setState((s) => ({ ...s, loading: true, error: null }));
+        const ctrl = new AbortController();
+        ctrlRef.current?.abort();
+        ctrlRef.current = ctrl;
+        const timer = setTimeout(() => {
+            src
+                .search(query.trim(), { signal: ctrl.signal, locale })
+                .then((res) => {
+                if (ctrl.signal.aborted)
+                    return;
+                remember(src, res.items);
+                pageCache.set(cacheKey, { items: res.items, nextCursor: res.nextCursor, at: Date.now() });
+                setState({ items: res.items, nextCursor: res.nextCursor, loading: false, loadingMore: false, error: null, query });
+            })
+                .catch((e) => {
+                if (ctrl.signal.aborted || isAbort(e))
+                    return;
+                setState((s) => ({ ...s, loading: false, error: e instanceof Error ? e.message : String(e) }));
+            });
+        }, query.trim() ? 200 : 0);
+        return () => {
+            clearTimeout(timer);
+            ctrl.abort();
+        };
+    }, [enabled, query, attempt, locale, sourceRef, source.key]);
+    const loadMore = React.useCallback(() => {
+        const src = sourceRef.current;
+        if (!state.nextCursor || state.loadingMore)
+            return;
+        const ctrl = new AbortController();
+        ctrlRef.current = ctrl;
+        setState((s) => ({ ...s, loadingMore: true }));
+        src
+            .search(query.trim(), { signal: ctrl.signal, cursor: state.nextCursor, locale })
+            .then((res) => {
+            if (ctrl.signal.aborted)
+                return;
+            remember(src, res.items);
+            setState((s) => ({ ...s, items: [...s.items, ...res.items], nextCursor: res.nextCursor, loadingMore: false }));
+        })
+            .catch((e) => {
+            if (ctrl.signal.aborted || isAbort(e))
+                return;
+            setState((s) => ({ ...s, loadingMore: false, error: e instanceof Error ? e.message : String(e) }));
+        });
+    }, [locale, query, sourceRef, state.loadingMore, state.nextCursor]);
+    const retry = React.useCallback(() => {
+        pageCache.delete(`${sourceRef.current.key}\u0000${query.trim()}`);
+        setAttempt((n) => n + 1);
+    }, [query, sourceRef]);
+    return { ...state, loadMore, retry };
+}
+/** Resolves ids → records through the cache, `known` records and `getByIds`. */
+function useResolvedRecords(source, ids, known) {
+    const sourceRef = useLatest(source);
+    const [, bump] = React.useReducer((n) => n + 1, 0);
+    const [pending, setPending] = React.useState(() => new Set());
+    const [missing, setMissing] = React.useState(() => new Set());
+    if (known?.length)
+        remember(source, known);
+    const idsKey = ids.join("\u0000");
+    React.useEffect(() => {
+        const src = sourceRef.current;
+        const unresolved = ids.filter((id) => !cached(src, id) && !missing.has(id));
+        if (unresolved.length === 0)
+            return;
+        if (!src.getByIds) {
+            setMissing((m) => new Set([...m, ...unresolved]));
+            return;
+        }
+        const ctrl = new AbortController();
+        setPending(new Set(unresolved));
+        src
+            .getByIds(unresolved, ctrl.signal)
+            .then((rs) => {
+            if (ctrl.signal.aborted)
+                return;
+            remember(src, rs);
+            const found = new Set(rs.map((r) => src.getId(r)));
+            const gone = unresolved.filter((id) => !found.has(id));
+            if (gone.length)
+                setMissing((m) => new Set([...m, ...gone]));
+            setPending(new Set());
+            bump();
+        })
+            .catch((e) => {
+            if (ctrl.signal.aborted || isAbort(e))
+                return;
+            setPending(new Set());
+            setMissing((m) => new Set([...m, ...unresolved]));
+        });
+        return () => ctrl.abort();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [idsKey, source.key]);
+    return ids.map((id) => ({ id, record: cached(source, id), pending: pending.has(id), missing: missing.has(id) && !cached(source, id) }));
+}
+/* ------------------------------------------------------------------ */
+/* Props                                                               */
+/* ------------------------------------------------------------------ */
+const recordPickerLabels = {
+    placeholder: "Select…",
+    placeholderMultiple: "Add…",
+    search: "Search…",
+    searching: "Searching…",
+    empty: "No results",
+    noResultsFor: "No results for “{query}”",
+    create: "Create “{query}”",
+    creating: "Creating…",
+    browse: "Browse all",
+    recent: "Recent",
+    results: "{count, plural, =0 {No results} one {# result} other {# results}}",
+    loadMore: "Load more",
+    unknown: "Unknown record",
+    max: "{max, plural, one {You can pick # record} other {You can pick up to # records}}",
+    error: "Couldn't load results",
+    retry: "Try again",
+    clear: "Clear selection",
+    add: "Add",
+    change: "Change",
+    open: "Open {label}",
+    remove: "Remove {label}",
+    browseTitle: "Browse",
+    selectCount: "{count, plural, =0 {Select} one {Select # record} other {Select # records}}",
+    cancel: "Cancel",
+    resolving: "Loading selection…",
+    selectedCount: "{count, plural, one {# selected} other {# selected}}",
+};
+const EMPTY_IDS = [];
+/* ------------------------------------------------------------------ */
+/* Pieces                                                              */
+/* ------------------------------------------------------------------ */
+function Highlight({ text, query, locale }) {
+    if (!query.trim())
+        return _jsx(_Fragment, { children: text });
+    return (_jsx(_Fragment, { children: highlightParts(text, query, locale).map((p, i) => p.match ? (_jsx("mark", { className: "bg-transparent font-semibold text-fg", children: p.text }, i)) : (_jsx(React.Fragment, { children: p.text }, i))) }));
+}
+function RecordAvatar({ source, record, size }) {
+    const a = source.getAvatar?.(record);
+    if (!a)
+        return null;
+    return _jsx(Avatar, { name: a.name, src: a.src, shape: a.shape, size: size, "aria-hidden": true });
+}
+/** Option look: highlight follows the active descendant, not `aria-selected` (that marks the picked records). */
+function optionClass(active, extra, size = "md") {
+    return cn(itemVariants({ size }), "aria-selected:bg-transparent", active && "bg-hover aria-selected:bg-hover", extra);
+}
+/** Default option row. */
+function DefaultRecordRow({ source, record, query, locale }) {
+    const desc = source.getDescription?.(record);
+    return (_jsxs(_Fragment, { children: [_jsx(RecordAvatar, { source: source, record: record, size: "sm" }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate", children: _jsx(Highlight, { text: source.getLabel(record), query: query, locale: locale }) }), desc ? (_jsx("span", { className: cn(itemSlots.description, "truncate"), children: _jsx(Highlight, { text: desc, query: query, locale: locale }) })) : null] })] }));
+}
+/** The search box + listbox, shared by the popover and inline modes. */
+function RecordPickerPanel(props) {
+    const { source, multiple, selectedIds, max, t, close } = props;
+    const { locale } = useLocale();
+    const [query, setQuery] = React.useState("");
+    const [creating, setCreating] = React.useState(false);
+    const search = useRecordSearch(source, query, true, locale);
+    const listId = React.useId();
+    const optionId = (key) => `${listId}-${key.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+    const selectedSet = React.useMemo(() => new Set(selectedIds), [selectedIds]);
+    const atMax = multiple && max !== undefined && selectedIds.length >= max;
+    const recentRecords = React.useMemo(() => {
+        if (props.recent === false || query.trim())
+            return [];
+        if (props.recent)
+            return props.recent;
+        return (recentCache.get(source.key) ?? []).map((id) => cached(source, id)).filter((r) => r !== undefined);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [props.recent, query, source.key, search.items]);
+    const entries = React.useMemo(() => {
+        const out = [];
+        const searching = query.trim().length > 0;
+        for (const a of props.actions ?? []) {
+            if (searching && a.hideWhileSearching !== false)
+                continue;
+            out.push({ kind: "action", key: `action:${a.id}`, action: a });
+        }
+        const recentIds = new Set();
+        for (const r of recentRecords) {
+            const id = source.getId(r);
+            recentIds.add(id);
+            const disabled = Boolean(props.getDisabled?.(r)) || (atMax && !selectedSet.has(id));
+            out.push({ kind: "record", key: `recent:${id}`, record: r, group: t("recent"), disabled });
+        }
+        for (const r of search.items) {
+            const id = source.getId(r);
+            if (recentIds.has(id))
+                continue;
+            const disabled = Boolean(props.getDisabled?.(r)) || (atMax && !selectedSet.has(id));
+            out.push({ kind: "record", key: `r:${id}`, record: r, group: props.getGroup?.(r) ?? (recentIds.size ? "\u0000all" : undefined), disabled });
+        }
+        if (props.onCreate && searching && !search.loading && !atMax) {
+            const exact = search.items.some((r) => source.getLabel(r).trim().toLocaleLowerCase(locale) === query.trim().toLocaleLowerCase(locale));
+            if (!exact)
+                out.push({ kind: "create", key: "create" });
+        }
+        if (search.nextCursor && !search.loading)
+            out.push({ kind: "more", key: "more" });
+        return out;
+    }, [atMax, locale, props, query, recentRecords, search.items, search.loading, search.nextCursor, selectedSet, source, t]);
+    const enabled = entries.filter((e) => !(e.kind === "record" && e.disabled));
+    const [activeKey, setActiveKey] = React.useState(null);
+    const active = enabled.find((e) => e.key === activeKey) ?? enabled[0] ?? null;
+    const listRef = React.useRef(null);
+    React.useEffect(() => {
+        if (!active)
+            return;
+        const els = listRef.current?.querySelectorAll("[data-key]") ?? [];
+        for (const el of els)
+            if (el.dataset.key === active.key)
+                el.scrollIntoView?.({ block: "nearest" });
+    }, [active]);
+    const activate = async (e) => {
+        if (!e)
+            return;
+        if (e.kind === "action") {
+            e.action.onSelect({ select: (r) => void props.onPick(r), close, query });
+        }
+        else if (e.kind === "record") {
+            if (e.disabled)
+                return;
+            await props.onPick(e.record);
+        }
+        else if (e.kind === "create" && props.onCreate) {
+            setCreating(true);
+            try {
+                const r = await props.onCreate(query.trim());
+                remember(source, [r]);
+                setQuery("");
+                await props.onPick(r);
+            }
+            finally {
+                setCreating(false);
+            }
+        }
+        else if (e.kind === "more") {
+            search.loadMore();
+        }
+    };
+    const move = (delta) => {
+        if (!enabled.length)
+            return;
+        const i = active ? enabled.indexOf(active) : -1;
+        const next = enabled[Math.max(0, Math.min(enabled.length - 1, i + delta))];
+        if (next)
+            setActiveKey(next.key);
+    };
+    const onKeyDown = (e) => {
+        switch (e.key) {
+            case "ArrowDown":
+                e.preventDefault();
+                move(1);
+                break;
+            case "ArrowUp":
+                e.preventDefault();
+                move(-1);
+                break;
+            case "PageDown":
+                e.preventDefault();
+                move(8);
+                break;
+            case "PageUp":
+                e.preventDefault();
+                move(-8);
+                break;
+            case "Enter":
+                e.preventDefault();
+                void activate(active);
+                break;
+            case "Backspace":
+                if (multiple && query === "" && props.onRemoveLast) {
+                    e.preventDefault();
+                    props.onRemoveLast();
+                }
+                break;
+            default:
+                break;
+        }
+    };
+    // Group consecutive entries for rendering.
+    const blocks = [];
+    for (const e of entries) {
+        const g = e.kind === "record" ? e.group : undefined;
+        const last = blocks[blocks.length - 1];
+        if (last && last.group === g)
+            last.entries.push(e);
+        else
+            blocks.push({ group: g, entries: [e] });
+    }
+    const renderEntry = (e) => {
+        const isActive = active?.key === e.key;
+        const common = {
+            id: optionId(e.key),
+            role: "option",
+            "data-key": e.key,
+            "data-active": isActive || undefined,
+            onMouseMove: () => setActiveKey(e.key),
+            onMouseDown: (ev) => ev.preventDefault(),
+            onClick: () => void activate(e),
+        };
+        if (e.kind === "record") {
+            const id = source.getId(e.record);
+            const selected = selectedSet.has(id);
+            return (_jsxs("div", { ...common, "aria-selected": selected, "aria-disabled": e.disabled || undefined, "data-state": selected ? "checked" : undefined, className: optionClass(isActive, "data-[state=checked]:font-normal min-h-9 gap-2.5 pe-2"), children: [props.renderItem ? props.renderItem(e.record, { selected, disabled: e.disabled, query }) : _jsx(DefaultRecordRow, { source: source, record: e.record, query: query, locale: locale }), _jsx(Check, { "aria-hidden": true, className: cn("ms-auto size-4 shrink-0 text-accent-ink transition-opacity", selected ? "opacity-100" : "opacity-0"), strokeWidth: 2.5 })] }, e.key));
+        }
+        if (e.kind === "action") {
+            return (_jsxs("div", { ...common, "aria-selected": false, className: optionClass(isActive, "font-medium text-accent-ink [&_svg]:text-accent-ink"), children: [e.action.icon ?? null, _jsx("span", { className: itemSlots.label, children: e.action.label })] }, e.key));
+        }
+        if (e.kind === "create") {
+            return (_jsxs("div", { ...common, "aria-selected": false, className: optionClass(isActive), children: [creating ? _jsx(Spinner, { size: "xs", tone: "muted" }) : _jsx(Plus, { "aria-hidden": true }), _jsx("span", { className: itemSlots.label, children: creating ? t("creating") : t("create", { query: query.trim() }) })] }, e.key));
+        }
+        return (_jsxs("div", { ...common, "aria-selected": false, className: optionClass(isActive, "justify-center text-fg-muted", "sm"), children: [search.loadingMore ? _jsx(Spinner, { size: "xs", tone: "muted" }) : null, t("loadMore")] }, e.key));
+    };
+    const resultCount = search.items.length;
+    const showEmpty = !search.loading && !search.error && entries.length === 0;
+    return (_jsxs("div", { "data-slot": "record-picker-panel", className: "flex min-h-0 flex-col", children: [props.header, _jsxs("div", { className: "flex items-center gap-2 border-b border-line px-3", children: [_jsx(Search, { "aria-hidden": true, className: "size-4 shrink-0 text-fg-subtle" }), _jsx("input", { role: "combobox", "aria-expanded": true, "aria-controls": listId, "aria-autocomplete": "list", "aria-activedescendant": active ? optionId(active.key) : undefined, "aria-label": props.ariaLabel ?? props.searchPlaceholder ?? t("search"), "aria-busy": search.loading || undefined, autoComplete: "off", spellCheck: false, disabled: props.disabled, placeholder: props.searchPlaceholder ?? t("search"), value: query, onChange: (e) => {
+                            setQuery(e.target.value);
+                            setActiveKey(null);
+                        }, onKeyDown: onKeyDown, ...props.inputProps, className: "h-10 min-w-0 flex-1 bg-transparent text-sm text-fg outline-none placeholder:text-fg-subtle" }), search.loading ? _jsx(Spinner, { size: "xs", tone: "muted" }) : null] }), _jsxs("div", { ref: listRef, id: listId, role: "listbox", "aria-multiselectable": multiple || undefined, "aria-label": props.ariaLabel ?? t("search"), className: cn("overflow-y-auto overscroll-contain p-1", props.inline ? "max-h-80" : "max-h-72"), children: [blocks.map((b, i) => b.group && b.group !== "\u0000all" ? (_jsxs("div", { role: "group", "aria-labelledby": `${listId}-g${i}`, children: [_jsx("div", { id: `${listId}-g${i}`, role: "presentation", className: itemSlots.groupLabel, children: b.group }), b.entries.map(renderEntry)] }, `g${i}`)) : b.group === "\u0000all" ? (_jsx("div", { role: "group", "aria-label": t("results", { count: resultCount }), className: "mt-1 border-t border-line pt-1", children: b.entries.map(renderEntry) }, `g${i}`)) : (_jsx(React.Fragment, { children: b.entries.map(renderEntry) }, `g${i}`))), search.loading && entries.length === 0 ? (_jsx("div", { className: "grid gap-2 p-2", "aria-hidden": true, children: [0, 1, 2].map((i) => (_jsxs("div", { className: "flex items-center gap-2.5", children: [_jsx(Skeleton, { shape: "circle", className: "size-6" }), _jsx(Skeleton, { className: "h-3 flex-1", style: { maxWidth: `${70 - i * 15}%` } })] }, i))) })) : null] }), showEmpty ? _jsx("p", { className: "px-3 pb-4 pt-2 text-center text-sm text-fg-muted", children: query.trim() ? t("noResultsFor", { query: query.trim() }) : t("empty") }) : null, search.error ? (_jsxs("div", { className: "flex items-center gap-2 px-3 pb-3 pt-1 text-sm text-fg-muted", children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "size-4 text-warning" }), _jsx("span", { className: "flex-1", children: t("error") }), _jsxs(Button, { size: "xs", variant: "ghost", onClick: search.retry, children: [_jsx(RotateCw, { "aria-hidden": true }), " ", t("retry")] })] })) : null, atMax ? _jsx("p", { className: "px-3 pb-2 text-xs text-fg-muted", children: t("max", { max }) }) : null, _jsx("span", { role: "status", "aria-live": "polite", className: "sr-only", children: search.loading ? t("searching") : t("results", { count: resultCount }) }), props.onBrowse ? (_jsxs("div", { className: "flex items-center justify-between gap-2 border-t border-line px-2 py-1.5", children: [_jsx("span", { className: "ps-1 text-xs text-fg-subtle", children: multiple && selectedIds.length ? t("selectedCount", { count: selectedIds.length }) : null }), _jsxs(Button, { size: "xs", variant: "ghost", onClick: props.onBrowse, children: [_jsx(LayoutList, { "aria-hidden": true }), " ", t("browse")] })] })) : null] }));
+}
+/** Built-in browse dialog: bigger search list with checkboxes, load more and a confirm step. */
+function RecordPickerBrowse({ source, open, onOpenChange, multiple, selectedIds, max, onPick, getDisabled, t, onCloseAutoFocus, }) {
+    const { locale } = useLocale();
+    const [query, setQuery] = React.useState("");
+    const [draft, setDraft] = React.useState(selectedIds);
+    const search = useRecordSearch(source, query, open, locale);
+    React.useEffect(() => {
+        if (open) {
+            setDraft(selectedIds);
+            setQuery("");
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open]);
+    const atMax = max !== undefined && draft.length >= max;
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { size: "lg", onCloseAutoFocus: onCloseAutoFocus, children: [_jsx(DialogHeader, { title: t("browseTitle") }), _jsxs(DialogBody, { className: "grid gap-3", children: [_jsxs("div", { className: cn(controlVariants({ size: "md" })), children: [_jsx(Search, { "aria-hidden": true, className: "text-fg-subtle" }), _jsx("input", { "data-autofocus": true, "aria-label": t("search"), placeholder: t("search"), value: query, onChange: (e) => setQuery(e.target.value), className: "h-full min-w-0 flex-1 bg-transparent outline-none placeholder:text-fg-subtle" }), search.loading ? _jsx(Spinner, { size: "xs", tone: "muted" }) : null] }), _jsxs("ul", { className: "grid max-h-[min(26rem,55vh)] overflow-y-auto overscroll-contain rounded-ui border border-line", "aria-busy": search.loading || undefined, children: [search.items.map((r) => {
+                                    const id = source.getId(r);
+                                    const checked = draft.includes(id);
+                                    const disabled = Boolean(getDisabled?.(r)) || (multiple && atMax && !checked);
+                                    const desc = source.getDescription?.(r);
+                                    const body = (_jsxs(_Fragment, { children: [_jsx(RecordAvatar, { source: source, record: r, size: "md" }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate text-sm font-medium text-fg", children: _jsx(Highlight, { text: source.getLabel(r), query: query, locale: locale }) }), desc ? _jsx("span", { className: "block truncate text-xs text-fg-subtle", children: desc }) : null] })] }));
+                                    return (_jsx("li", { className: "border-b border-line last:border-b-0", children: multiple ? (_jsxs("label", { className: cn("flex cursor-pointer items-center gap-3 px-3 py-2.5 hover:bg-hover", disabled && "pointer-events-none opacity-45"), children: [_jsx(Checkbox, { size: "sm", checked: checked, disabled: disabled, "aria-label": source.getLabel(r), onCheckedChange: (c) => setDraft((d) => (c === true ? [...d, id] : d.filter((x) => x !== id))) }), body] })) : (_jsxs("button", { type: "button", disabled: disabled, "aria-pressed": checked, onClick: () => {
+                                                onPick([r]);
+                                                onOpenChange(false);
+                                            }, className: "flex w-full items-center gap-3 px-3 py-2.5 text-start hover:bg-hover focus-ring disabled:opacity-45 aria-pressed:bg-selected", children: [body, checked ? _jsx(Check, { "aria-hidden": true, className: "size-4 text-accent-ink" }) : null] })) }, id));
+                                }), !search.loading && search.items.length === 0 ? (_jsx("li", { className: "px-3 py-8 text-center text-sm text-fg-muted", children: query.trim() ? t("noResultsFor", { query: query.trim() }) : t("empty") })) : null, search.nextCursor ? (_jsx("li", { className: "p-1.5", children: _jsx(Button, { size: "sm", variant: "ghost", block: true, loading: search.loadingMore, onClick: search.loadMore, children: t("loadMore") }) })) : null] })] }), multiple ? (_jsxs(DialogFooter, { children: [_jsx(Button, { onClick: () => onOpenChange(false), children: t("cancel") }), _jsx(Button, { variant: "primary", onClick: () => {
+                                onPick(draft.map((id) => cached(source, id)).filter((r) => r !== undefined));
+                                onOpenChange(false);
+                            }, children: t("selectCount", { count: draft.length }) })] })) : null] }) }));
+}
+/* ------------------------------------------------------------------ */
+/* RecordPicker                                                        */
+/* ------------------------------------------------------------------ */
+const chipClass = "inline-flex h-6 max-w-full min-w-0 shrink-0 items-center gap-1.5 rounded-full bg-selected ps-1 pe-2 text-xs font-medium leading-none text-fg";
+function RecordPickerInner(props, forwardedRef) {
+    const { source, renderItem, getDisabled, getGroup, onCreate, browse, recent, actions, resolveSelection, selectedRecords, display = "chip", mode = "popover", size = "md", placeholder, searchPlaceholder, renderTrigger, header, labels, className, contentClassName, clearable, } = props;
+    const multiple = props.multiple === true;
+    const control = useFieldControl({
+        id: props.id,
+        name: props.name,
+        disabled: props.disabled,
+        readOnly: props.readOnly,
+        required: props.required,
+        "aria-describedby": props["aria-describedby"],
+        "aria-labelledby": props["aria-labelledby"],
+        "aria-invalid": props["aria-invalid"] ?? (props.invalid ? true : undefined),
+    });
+    const cardTriggerId = React.useId();
+    const disabled = Boolean(control.disabled);
+    const readOnly = Boolean(control.readOnly);
+    const t = useLabels("recordPicker", recordPickerLabels, labels);
+    const container = usePortalContainer();
+    const triggerRef = React.useRef(null);
+    // value as an array internally
+    const toArray = (v) => (v === undefined ? undefined : Array.isArray(v) ? v : v === null ? [] : [v]);
+    const [ids, setIdsRaw] = useControllableState({
+        value: toArray(props.value),
+        defaultValue: () => toArray(props.defaultValue) ?? EMPTY_IDS,
+        name: "RecordPicker",
+    });
+    const onValueChangeRef = useLatest(props.onValueChange);
+    const setIds = (next) => {
+        setIdsRaw(next);
+        const rs = next.map((id) => cached(source, id)).filter((r) => r !== undefined);
+        if (multiple)
+            onValueChangeRef.current?.(next, rs);
+        else
+            onValueChangeRef.current?.(next[0] ?? null, rs[0] ?? null);
+    };
+    const [open, setOpen] = useControllableState({ value: props.open, defaultValue: props.defaultOpen ?? false, onChange: props.onOpenChange, name: "RecordPicker" });
+    const [browseOpen, setBrowseOpen] = React.useState(false);
+    const resolved = useResolvedRecords(source, ids, selectedRecords);
+    const selected = resolved.filter((x) => x.record).map((x) => x.record);
+    const unknownIds = resolved.filter((x) => x.missing).map((x) => x.id);
+    const max = multiple ? props.max : undefined;
+    const pick = async (r) => {
+        let picked = [r];
+        if (resolveSelection) {
+            const res = await resolveSelection(r);
+            picked = Array.isArray(res) ? res : [res];
+        }
+        remember(source, picked);
+        const pickedIds = picked.map((p) => source.getId(p));
+        pushRecent(source, pickedIds);
+        if (!multiple) {
+            setIds(pickedIds.slice(0, 1));
+            setOpen(false);
+            return;
+        }
+        if (picked.length === 1 && ids.includes(pickedIds[0])) {
+            setIds(ids.filter((x) => x !== pickedIds[0]));
+            return;
+        }
+        let next = [...ids, ...pickedIds.filter((x) => !ids.includes(x))];
+        if (max !== undefined)
+            next = next.slice(0, max);
+        setIds(next);
+    };
+    const remove = (id) => setIds(ids.filter((x) => x !== id));
+    const placeholderText = placeholder ?? (multiple ? t("placeholderMultiple") : t("placeholder"));
+    const showClear = !multiple && (clearable ?? !control.required) && ids.length > 0 && !disabled && !readOnly;
+    const labelOf = (r) => source.getLabel(r);
+    const hidden = props.name || control.name ? (ids.map((id) => _jsx("input", { type: "hidden", name: control.name, value: id }, id)).concat(ids.length === 0 && !multiple ? [_jsx("input", { type: "hidden", name: control.name, value: "" }, "__empty")] : [])) : null;
+    const openBrowse = () => {
+        setOpen(false);
+        setBrowseOpen(true);
+    };
+    const panel = (_jsx(RecordPickerPanel, { source: source, multiple: multiple, selectedIds: ids, max: max, onPick: pick, onRemoveLast: multiple && ids.length ? () => remove(ids[ids.length - 1]) : undefined, onCreate: onCreate, onBrowse: browse ? openBrowse : undefined, renderItem: renderItem, getDisabled: getDisabled, getGroup: getGroup, recent: recent, actions: actions, close: () => setOpen(false), t: t, searchPlaceholder: searchPlaceholder, header: header, inline: mode === "inline", disabled: disabled || readOnly, ariaLabel: mode === "inline" ? props["aria-label"] : undefined, inputProps: mode === "inline" ? { id: control.id, "aria-labelledby": control["aria-labelledby"], "aria-describedby": control["aria-describedby"] } : undefined }));
+    const browseDialog = browse === true ? (_jsx(RecordPickerBrowse, { source: source, open: browseOpen, onOpenChange: setBrowseOpen, multiple: multiple, selectedIds: ids, max: max, getDisabled: getDisabled, t: t, onCloseAutoFocus: (e) => {
+            e.preventDefault();
+            triggerRef.current?.focus();
+        }, onPick: (rs) => {
+            remember(source, rs);
+            const picked = rs.map((r) => source.getId(r));
+            pushRecent(source, picked);
+            setIds(multiple ? picked : picked.slice(0, 1));
+        } })) : typeof browse === "function" && browseOpen ? (browse({
+        selectedIds: ids,
+        multiple,
+        close: () => setBrowseOpen(false),
+        onPick: (rs) => {
+            remember(source, rs);
+            const picked = rs.map((r) => source.getId(r));
+            setIds(multiple ? picked : picked.slice(0, 1));
+            setBrowseOpen(false);
+        },
+    })) : null;
+    /* ---------- inline mode ---------- */
+    if (mode === "inline") {
+        return (_jsxs("div", { ref: forwardedRef, "data-slot": "record-picker", "data-mode": "inline", "aria-invalid": control["aria-invalid"], className: cn("surface-2 overflow-hidden rounded-ui border border-line aria-invalid:border-danger", disabled && "pointer-events-none opacity-50", className), children: [panel, hidden, browseDialog] }));
+    }
+    /* ---------- selected rendering ---------- */
+    const renderChip = (x) => {
+        if (x.pending)
+            return _jsx(Skeleton, { className: "h-6 w-24 rounded-full", "aria-hidden": true }, x.id);
+        if (!x.record) {
+            return (_jsxs("span", { "data-slot": "record-chip", "data-unknown": "", title: x.id, className: cn(chipClass, "tone-warning tone-soft ps-2"), children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "size-3" }), t("unknown"), !readOnly && !disabled ? _jsx(ChipRemoveButton, { onRemove: () => remove(x.id), itemLabel: t("unknown") }) : null] }, x.id));
+        }
+        const r = x.record;
+        const label = labelOf(r);
+        const href = source.href?.(r);
+        const a = source.getAvatar?.(r);
+        return (_jsxs("span", { "data-slot": "record-chip", className: cn(chipClass, !a && "ps-2"), children: [a ? _jsx(Avatar, { name: a.name, src: a.src, shape: a.shape, size: "xs", "aria-hidden": true }) : null, href ? (_jsx(SmartLink, { href: href, className: "min-w-0 truncate underline-offset-2 hover:underline focus-ring rounded-sm", children: label })) : (_jsx("span", { className: "min-w-0 truncate", children: label })), !readOnly && !disabled ? _jsx(ChipRemoveButton, { onRemove: () => remove(x.id), itemLabel: label, labels: { remove: t.labels.remove } }) : null] }, x.id));
+    };
+    const renderCard = (x) => {
+        if (x.pending) {
+            return (_jsxs("div", { className: "flex items-center gap-3 rounded-ui border border-line bg-surface-2 p-3", "aria-hidden": true, children: [_jsx(Skeleton, { shape: "circle", className: "size-10" }), _jsxs("div", { className: "grid flex-1 gap-1.5", children: [_jsx(Skeleton, { className: "h-3 w-1/2" }), _jsx(Skeleton, { className: "h-2.5 w-1/3" })] })] }, x.id));
+        }
+        const r = x.record;
+        const label = r ? labelOf(r) : t("unknown");
+        const href = r ? source.href?.(r) : undefined;
+        const desc = r ? source.getDescription?.(r) : x.id;
+        return (_jsxs("div", { "data-slot": "record-card", "data-unknown": r ? undefined : "", className: cn("group/card relative flex items-center gap-3 rounded-ui border border-line bg-surface-2 p-3", !r && "tone-warning tone-soft border-transparent"), children: [r ? _jsx(RecordAvatar, { source: source, record: r, size: "lg" }) : _jsx(TriangleAlert, { "aria-hidden": true, className: "size-5 text-warning" }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "truncate text-sm font-medium text-fg", children: label }), desc ? _jsx("div", { className: "truncate text-xs text-fg-muted", children: desc }) : null] }), href ? (_jsx(IconButton, { asChild: true, label: t("open", { label }), size: "sm", variant: "ghost", tooltip: false, children: _jsx(SmartLink, { href: href, children: _jsx(ExternalLink, {}) }) })) : null, !readOnly && !disabled ? (_jsx(IconButton, { label: t("remove", { label }), size: "sm", variant: "ghost", tooltip: false, onClick: () => remove(x.id), children: _jsx(X, {}) })) : null] }, x.id));
+    };
+    /* ---------- trigger ---------- */
+    const triggerA11y = {
+        id: control.id,
+        "aria-label": props["aria-label"],
+        "aria-labelledby": control["aria-labelledby"],
+        "aria-describedby": mergeIds(control["aria-describedby"]),
+        "aria-invalid": control["aria-invalid"],
+        // No aria-required: the triggers are buttons, where it isn't allowed (axe aria-allowed-attr).
+        // The Field marks the label as required and the hidden input carries the constraint.
+        "aria-haspopup": "listbox",
+        disabled,
+    };
+    let body;
+    if (readOnly) {
+        body =
+            display === "card" ? (_jsxs("div", { ref: forwardedRef, "data-slot": "record-picker", "data-readonly": "", className: cn("grid gap-2", className), children: [resolved.map(renderCard), hidden] })) : (_jsxs("div", { ref: forwardedRef, id: control.id, "data-slot": "record-picker", "data-readonly": "", role: "group", "aria-labelledby": control["aria-labelledby"], "aria-describedby": control["aria-describedby"], className: cn(controlVariants({ size, multiline: multiple || undefined }), "flex-wrap gap-1.5", className), children: [resolved.length ? resolved.map(renderChip) : _jsx("span", { className: "text-fg-subtle", children: "\u2014" }), hidden] }));
+        return body;
+    }
+    const content = (_jsx(PopoverPrimitive.Portal, { container: container, children: _jsx(Layer, { asChild: true, children: _jsx(PopoverPrimitive.Content, { "data-slot": "record-picker-content", "aria-label": props["aria-label"] ?? searchPlaceholder ?? t("search"), align: "start", sideOffset: 6, collisionPadding: 12, className: cn("surface-popover ui-pop z-(--z-popover) w-(--radix-popover-trigger-width) min-w-72 max-w-[calc(100vw-1.5rem)] overflow-hidden rounded-ui-lg outline-none", contentClassName), onOpenAutoFocus: (e) => {
+                    e.preventDefault();
+                    e.currentTarget?.querySelector("input[role=combobox]")?.focus();
+                }, children: _jsx(FieldContextReset, { children: panel }) }) }) }));
+    if (renderTrigger) {
+        return (_jsxs(PopoverPrimitive.Root, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverPrimitive.Trigger, { asChild: true, ref: triggerRef, ...triggerA11y, children: renderTrigger({ selected, unknownIds, open, disabled, placeholder: placeholderText, getLabel: labelOf }) }), content, hidden, browseDialog] }));
+    }
+    if (display === "card") {
+        return (_jsxs(PopoverPrimitive.Root, { open: open, onOpenChange: setOpen, children: [_jsxs("div", { ref: forwardedRef, "data-slot": "record-picker", "data-display": "card", className: cn("grid gap-2", className), children: [resolved.map(renderCard), (multiple && (max === undefined || ids.length < max)) || !multiple ? (_jsx(PopoverPrimitive.Anchor, { asChild: true, children: _jsx("div", { children: _jsx(PopoverPrimitive.Trigger, { asChild: true, children: _jsxs(Button, { ref: triggerRef, size: "sm", variant: "secondary", ...triggerA11y, "aria-label": props["aria-label"], 
+                                        // The visible text ("Add", "Change") must stay part of the name next to the label.
+                                        id: control.id ?? cardTriggerId, "aria-labelledby": control["aria-labelledby"] ? `${control["aria-labelledby"]} ${control.id ?? cardTriggerId}` : undefined, children: [_jsx(Plus, { "aria-hidden": true }), " ", !multiple && ids.length ? t("change") : placeholder ?? t("add")] }) }) }) })) : null, hidden] }), content, browseDialog] }));
+    }
+    if (multiple) {
+        return (_jsxs(PopoverPrimitive.Root, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverPrimitive.Anchor, { asChild: true, children: _jsxs("div", { ref: forwardedRef, "data-slot": "record-picker", "data-state": open ? "open" : "closed", "aria-invalid": control["aria-invalid"], "aria-disabled": disabled || undefined, className: cn(controlVariants({ size, multiline: true }), "min-h-(--control-h) flex-wrap items-center gap-1.5 py-1.5 ps-1.5", className), onClick: (e) => {
+                            if (e.target === e.currentTarget && !disabled)
+                                triggerRef.current?.click();
+                        }, children: [resolved.map(renderChip), _jsx(PopoverPrimitive.Trigger, { asChild: true, children: _jsxs("button", { ref: triggerRef, type: "button", ...triggerA11y, className: "inline-flex h-6 min-w-0 flex-1 items-center gap-1 rounded-ui-sm px-1.5 text-start text-fg-subtle outline-none hover:text-fg focus-visible:text-fg disabled:cursor-not-allowed [&_svg]:size-3.5", children: [_jsx(Plus, { "aria-hidden": true }), _jsx("span", { className: "truncate", children: placeholderText })] }) }), hidden] }) }), content, browseDialog] }));
+    }
+    const current = resolved[0];
+    return (_jsxs(PopoverPrimitive.Root, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverPrimitive.Anchor, { asChild: true, children: _jsxs("div", { ref: forwardedRef, "data-slot": "record-picker", "data-state": open ? "open" : "closed", "aria-invalid": control["aria-invalid"], "aria-disabled": disabled || undefined, className: cn(controlVariants({ size }), "p-0", className), children: [_jsx(PopoverPrimitive.Trigger, { asChild: true, children: _jsxs("button", { ref: triggerRef, type: "button", ...triggerA11y, "aria-label": undefined, className: cn("flex h-full min-w-0 flex-1 items-center gap-2 rounded-[inherit] ps-3 text-start outline-none disabled:cursor-not-allowed", showClear ? "pe-1" : "pe-3"), children: [props["aria-label"] && !control["aria-labelledby"] ? _jsxs("span", { className: "sr-only", children: [props["aria-label"], ", "] }) : null, current?.pending ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "sr-only", children: t("resolving") }), _jsx(Skeleton, { "aria-hidden": true, className: "h-3 w-32" })] })) : current?.record ? (_jsxs(_Fragment, { children: [_jsx(RecordAvatar, { source: source, record: current.record, size: size === "lg" ? "sm" : "xs" }), _jsx("span", { className: "min-w-0 flex-1 truncate", children: labelOf(current.record) })] })) : current?.missing ? (_jsxs("span", { className: "flex min-w-0 flex-1 items-center gap-1.5 truncate text-warning", children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "size-3.5" }), " ", t("unknown")] })) : (_jsx("span", { className: "min-w-0 flex-1 truncate text-fg-subtle", children: placeholderText })), !showClear ? _jsx(ChevronsUpDown, { "aria-hidden": true, className: "ms-auto size-4 shrink-0 text-fg-subtle" }) : null] }) }), showClear ? (_jsx("button", { type: "button", "aria-label": t("clear"), onClick: () => {
+                                setIds([]);
+                                triggerRef.current?.focus();
+                            }, className: "me-1.5 inline-flex size-6 shrink-0 items-center justify-center rounded-ui-sm text-fg-subtle hover:bg-hover hover:text-fg focus-ring [&_svg]:size-3.5", children: _jsx(X, { "aria-hidden": true }) })) : null, hidden] }) }), content, browseDialog] }));
+}
+/**
+ * Link one or many related records from any collection: a contact to a company, a post to its
+ * author, an order to a customer, a task to a project. Async search with debounce, abort and
+ * paging; recent picks; inline create; a browse dialog for big sets; chips or cards; ids → labels
+ * resolution with a skeleton and an "Unknown record" state for deleted records.
+ *
+ * ```tsx
+ * const companies: RecordSource<Company> = {
+ *   key: "companies",
+ *   search: (q, { signal, cursor }) => api.companies.search({ q, cursor }, { signal }),
+ *   getByIds: (ids, signal) => api.companies.byIds(ids, { signal }),
+ *   getId: (c) => c.id, getLabel: (c) => c.name, getDescription: (c) => c.domain,
+ * };
+ * <Field label="Company"><RecordPicker source={companies} value={companyId} onValueChange={setCompanyId} /></Field>
+ * ```
+ */
+export const RecordPicker = React.forwardRef(RecordPickerInner);