@asteby/metacore-runtime-react 49.5.0 → 49.7.0

package/dist/record-picker.js

@@ -0,0 +1,372 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// RecordPicker — THE "pick a related record" control of the runtime.
+//
+// Before it, every surface carried its own picker: the declarative
+// DynamicSelectField, the hand-written EntitySelect, the business
+// Customer/Product/Vehicle pickers, the DocumentEditor's product cell, the
+// legacy `search` field of the generic modal and the multi-select of `ref`
+// arrays — each with its own search loop, list markup, keyboard handling and
+// create button. They are now thin configurations of this one primitive:
+//
+//   - data: caller-owned `items` (options resolver, static list, a search the
+//     caller drives) or a `search(q, signal)` fetcher run here with debounce,
+//     cancellation and a min-chars gate; loading / empty / error states;
+//   - selection: single or `multiple` (chips with remove);
+//   - create / edit: "+" joined to the trigger when empty, pencil when a value
+//     is selected, "Crear …" at the foot of the list prefilled with the search
+//     (record-picker-actions.tsx);
+//   - rich options by props/slots: lead (avatar / initials / thumbnail),
+//     subtitle (SKU, RFC…), trailing (price / stock), or a full `renderItem`;
+//   - presentation: `trigger="button"` (select-like, search inside the list)
+//     or `trigger="input"` (type in the field itself; `freeText` keeps the text
+//     as the value, e.g. a free invoice line), `variant="field" | "cell"`;
+//   - the list is ALWAYS portaled (never clipped by a table / modal overflow),
+//     collision-aware (flips when there is no room) and stacked above dialogs;
+//   - keyboard: ↑/↓/Home/End move, Enter picks, Esc closes (without closing the
+//     dialog around it), Tab closes and moves on; ARIA combobox + listbox with
+//     aria-activedescendant (focus never leaves the text box).
+//
+// Built only on @asteby/metacore-ui primitives (Popover, Button, Input, Badge),
+// so it themes (light / dark) with the host.
+import { useCallback, useEffect, useId, useRef, useState, } from 'react';
+import { Check, ChevronsUpDown, Loader2, Plus, Search, X } from 'lucide-react';
+import { Badge, Button, Input, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, } from '@asteby/metacore-ui/primitives';
+import { JOINED_TRIGGER_CLASS, RecordPickerAction, hasRecordPickerAction } from './record-picker-actions';
+import { useDebouncedValue } from './use-debounced-value';
+/**
+ * z-index of the portaled list. Dialogs/sheets sit at 50; the list must stay
+ * above the modal it was opened from regardless of portal order.
+ */
+export const RECORD_PICKER_Z_INDEX = 60;
+const cx = (...parts) => parts.filter(Boolean).join(' ');
+/** Debounced async search with cancellation. `search` must be stable (useCallback). */
+export function useRecordSearch(query, search, opts = {}) {
+    const { minChars = 2, delay = 250, enabled = true } = opts;
+    const trimmed = query.trim();
+    const q = useDebouncedValue(trimmed, delay);
+    const [results, setResults] = useState([]);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(false);
+    // The query the current results answer. Until it matches what was typed
+    // (debounce running, or the request not answered yet) the search is
+    // `pending` — so a list never flashes "no results" before searching.
+    const [doneFor, setDoneFor] = useState(null);
+    useEffect(() => {
+        if (!enabled || q.length < minChars) {
+            setResults((r) => (r.length ? [] : r));
+            setLoading(false);
+            setError(false);
+            setDoneFor(null);
+            return;
+        }
+        const ctrl = new AbortController();
+        setLoading(true);
+        setError(false);
+        search(q, ctrl.signal)
+            .then((rows) => {
+            if (!ctrl.signal.aborted)
+                setResults(rows);
+        })
+            .catch(() => {
+            if (!ctrl.signal.aborted) {
+                setResults([]);
+                setError(true);
+            }
+        })
+            .finally(() => {
+            if (!ctrl.signal.aborted) {
+                setLoading(false);
+                setDoneFor(q);
+            }
+        });
+        return () => ctrl.abort();
+    }, [q, search, minChars, enabled]);
+    return { results, loading, error, pending: enabled && trimmed.length >= minChars && doneFor !== trimmed };
+}
+const NO_SEARCH = () => Promise.resolve([]);
+/**
+ * Stable identity for a caller's search function: always calls the latest one,
+ * so an inline (non-memoized) fetcher doesn't re-trigger the search on every
+ * render.
+ */
+export function useLatestSearch(fn) {
+    const ref = useRef(fn);
+    ref.current = fn;
+    return useCallback((...args) => ref.current(...args), []);
+}
+const TABBABLE = 'a[href],button:not([disabled]),input:not([disabled]):not([type="hidden"]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+/** Focus the tabbable after `from` (skipping portaled popper content). */
+function focusNextAfter(from) {
+    if (!from || typeof document === 'undefined')
+        return;
+    const all = Array.from(document.querySelectorAll(TABBABLE)).filter((el) => el.tabIndex >= 0 && !el.closest('[data-radix-popper-content-wrapper]'));
+    const i = all.indexOf(from);
+    (all[i + 1] ?? from).focus();
+}
+function asKeys(value, multiple) {
+    if (multiple)
+        return Array.isArray(value) ? value.map(String) : [];
+    if (value == null || value === '' || Array.isArray(value))
+        return [];
+    return [String(value)];
+}
+export function RecordPicker(props) {
+    const { getKey, getLabel, items, search, debounceMs = 250, multiple = false, value, selected, onSelect, onClear, onRemove, renderItem, renderLead, getDescription, renderTrailing, renderValue, isItemDisabled, placeholder = 'Seleccionar…', searchPlaceholder = 'Buscar…', emptyText = 'Sin resultados', loadingText = 'Buscando…', errorText = 'No se pudo buscar. Inténtalo de nuevo.', minCharsText, clearLabel = 'Quitar selección', listLabel, entityLabel = '', onCreate, onEdit, createLabel, editLabel, createFooter = 'always', createFooterLabel, hideJoinedAction = false, trigger = 'button', variant = 'field', freeText = false, icon: Icon, id, ariaLabel, disabled = false, readOnly = false, invalid = false, slot, anchorSlot, contentSlot = 'record-picker-content', className, triggerClassName, triggerProps, inputRef, minListWidth = '14rem', after, below, beforeList, onInputKeyDown, onUnhandledKeyDown, } = props;
+    const isInput = trigger === 'input';
+    const minChars = props.minChars ?? (isInput ? 2 : 0);
+    const showCheck = props.showCheck ?? !isInput;
+    const closeOnSelect = props.closeOnSelect ?? !multiple;
+    const listId = useId();
+    const triggerRef = useRef(null);
+    const anchorRef = useRef(null);
+    const tabbingRef = useRef(false);
+    // open / query: controlled when the caller passes them.
+    const [openState, setOpenState] = useState(false);
+    const open = props.open ?? openState;
+    const { onOpenChange, onQueryChange } = props;
+    const controlledOpen = props.open !== undefined;
+    const setOpen = useCallback((o) => {
+        if (!controlledOpen)
+            setOpenState(o);
+        onOpenChange?.(o);
+    }, [controlledOpen, onOpenChange]);
+    const [queryState, setQueryState] = useState('');
+    const query = props.query ?? queryState;
+    const controlledQuery = props.query !== undefined;
+    const setQuery = useCallback((q) => {
+        if (!controlledQuery)
+            setQueryState(q);
+        onQueryChange?.(q);
+    }, [controlledQuery, onQueryChange]);
+    const trimmed = query.trim();
+    const belowMin = trimmed.length < minChars;
+    const listOpen = !disabled && !readOnly && open && (!isInput || !belowMin);
+    const internal = useRecordSearch(query, (search ?? NO_SEARCH), {
+        minChars,
+        delay: debounceMs,
+        enabled: !!search && !items && open && !disabled && !readOnly,
+    });
+    const rows = items ?? internal.results;
+    const loading = props.loading ?? (internal.loading || internal.pending);
+    const error = props.error ?? internal.error;
+    const keys = asKeys(value, multiple);
+    const hasValue = keys.length > 0;
+    const isSelected = (item) => keys.includes(getKey(item));
+    const single = !multiple ? (selected ?? null) : null;
+    const selectedList = multiple && Array.isArray(selected) ? selected : [];
+    const showFooter = !!onCreate &&
+        !loading &&
+        createFooter !== 'never' &&
+        (createFooter === 'always' || (rows.length === 0 && !belowMin && !error));
+    const count = rows.length + (showFooter ? 1 : 0);
+    // Highlight: the selected row when (re)opening, else the first. Keyed on the
+    // row ids (not the array identity) so a caller recomputing `items` on every
+    // render doesn't reset the keyboard position.
+    const [active, setActive] = useState(0);
+    const rowSig = rows.map(getKey).join('\u0001');
+    useEffect(() => {
+        const i = rows.findIndex((r) => keys.includes(getKey(r)));
+        setActive(i >= 0 ? i : 0);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [rowSig, trimmed, listOpen]);
+    useEffect(() => {
+        if (!listOpen || typeof document === 'undefined')
+            return;
+        const el = document.getElementById(`${listId}-o${active}`);
+        el?.scrollIntoView?.({ block: 'nearest' });
+    }, [active, listOpen, listId]);
+    const enabledAt = (i) => i === rows.length ? showFooter : !!rows[i] && !isItemDisabled?.(rows[i]);
+    const step = (from, dir) => {
+        for (let i = from + dir; i >= 0 && i < count; i += dir)
+            if (enabledAt(i))
+                return i;
+        return from;
+    };
+    const close = () => setOpen(false);
+    const runCreate = () => {
+        const q = trimmed;
+        close();
+        if (!freeText)
+            setQuery('');
+        onCreate?.(q);
+    };
+    const choose = (i) => {
+        if (i === rows.length && showFooter)
+            return runCreate();
+        const item = rows[i];
+        if (!item || isItemDisabled?.(item))
+            return;
+        onSelect(item);
+        if (closeOnSelect)
+            close();
+        if (!freeText && !multiple)
+            setQuery('');
+    };
+    const onKeyDown = (e) => {
+        if (onInputKeyDown) {
+            // Only a preventDefault() from the caller takes over (Radix may
+            // already have prevented Esc at the document level).
+            const before = e.defaultPrevented;
+            onInputKeyDown(e);
+            if (!before && e.defaultPrevented)
+                return;
+        }
+        if (listOpen && count > 0) {
+            if (e.key === 'ArrowDown') {
+                e.preventDefault();
+                setActive((a) => step(Math.min(a, count - 1), 1));
+                return;
+            }
+            if (e.key === 'ArrowUp') {
+                e.preventDefault();
+                setActive((a) => step(Math.min(a, count), -1));
+                return;
+            }
+            if (!isInput && (e.key === 'Home' || e.key === 'End')) {
+                e.preventDefault();
+                setActive(e.key === 'Home' ? step(-1, 1) : step(count, -1));
+                return;
+            }
+            if (e.key === 'Enter' && enabledAt(active)) {
+                e.preventDefault();
+                choose(active);
+                return;
+            }
+        }
+        if (isInput) {
+            if (listOpen && e.key === 'Escape') {
+                // Close the list, not the dialog around it.
+                e.preventDefault();
+                e.stopPropagation();
+                close();
+                return;
+            }
+            if (!listOpen && !freeText && e.key === 'ArrowDown' && !belowMin) {
+                e.preventDefault();
+                setOpen(true);
+                return;
+            }
+            if (e.key === 'Tab')
+                close();
+        }
+        else if (e.key === 'Tab' && !e.shiftKey) {
+            // Close and move on to the next field (not to the end of <body>,
+            // where the portaled list lives).
+            e.preventDefault();
+            tabbingRef.current = true;
+            close();
+            return;
+        }
+        onUnhandledKeyDown?.(e);
+    };
+    const activeId = listOpen && count > 0 && enabledAt(active) ? `${listId}-o${active}` : undefined;
+    // ---- the list (shared by both trigger modes) --------------------------
+    const status = (() => {
+        if (loading && rows.length === 0) {
+            return (_jsxs("div", { role: "status", className: "flex items-center justify-center gap-2 py-6 text-sm text-muted-foreground", "data-slot": "picker-loading", children: [_jsx(Loader2, { className: "size-4 animate-spin", "aria-hidden": true }), loadingText] }));
+        }
+        if (loading)
+            return null;
+        if (error) {
+            return (_jsx("p", { role: "alert", className: "px-2 py-4 text-center text-sm text-destructive", "data-slot": "picker-error", children: errorText }));
+        }
+        if (rows.length > 0)
+            return null;
+        if (belowMin && minChars > 0) {
+            return (_jsxs("div", { className: "flex flex-col items-center gap-1 py-6 text-muted-foreground", "data-slot": "picker-min-chars", children: [_jsx(Search, { className: "size-5", "aria-hidden": true }), _jsx("span", { className: "text-xs", children: minCharsText ?? `Escribe al menos ${minChars} caracteres` })] }));
+        }
+        return (_jsx("div", { className: "px-2 py-6 text-center text-sm text-muted-foreground", "data-slot": "picker-empty", children: emptyText }));
+    })();
+    const optionClass = (on, dis) => cx('relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden', on && 'bg-accent text-accent-foreground', dis && 'pointer-events-none opacity-50');
+    const list = (_jsxs("div", { className: "max-h-72 overflow-y-auto overflow-x-hidden overscroll-contain", "data-slot": "record-picker-list", children: [beforeList, status, _jsxs("ul", { id: listId, role: "listbox", "aria-label": listLabel ?? ariaLabel ?? entityLabel ?? undefined, "aria-multiselectable": multiple || undefined, className: cx('p-1', count === 0 && 'hidden'), children: [rows.map((item, i) => {
+                        const sel = isSelected(item);
+                        const dis = !!isItemDisabled?.(item);
+                        const on = i === active;
+                        const desc = getDescription?.(item);
+                        return (_jsx("li", { id: `${listId}-o${i}`, role: "option", "aria-selected": multiple ? sel : on, "aria-disabled": dis || undefined, "data-active": on || undefined, "data-selected": sel || undefined, "data-slot": "record-picker-option", className: optionClass(on, dis), onMouseDown: (e) => e.preventDefault(), onMouseMove: () => {
+                                if (!on && !dis)
+                                    setActive(i);
+                            }, onClick: () => choose(i), children: renderItem ? (renderItem(item, { active: on, selected: sel, disabled: dis })) : (_jsxs(_Fragment, { children: [showCheck ? (_jsx(Check, { className: cx('size-4 shrink-0', sel ? 'opacity-100' : 'opacity-0'), "aria-hidden": true })) : null, renderLead?.(item, 'option'), _jsxs("span", { className: "flex min-w-0 flex-1 flex-col", children: [_jsx("span", { className: "truncate", children: getLabel(item) }), desc != null && desc !== '' ? (_jsx("span", { className: "truncate text-xs text-muted-foreground", children: desc })) : null] }), renderTrailing ? (_jsx("span", { className: "ml-auto flex shrink-0 items-center gap-2", children: renderTrailing(item, 'option') })) : null] })) }, getKey(item)));
+                    }), showFooter ? (_jsxs(_Fragment, { children: [rows.length > 0 ? _jsx("li", { role: "presentation", className: "-mx-1 my-1 h-px bg-border" }) : null, _jsxs("li", { id: `${listId}-o${rows.length}`, role: "option", "aria-selected": active === rows.length, "data-active": active === rows.length || undefined, "data-slot": "picker-create", className: cx(optionClass(active === rows.length, false), 'text-primary'), onMouseDown: (e) => e.preventDefault(), onMouseMove: () => setActive(rows.length), onClick: runCreate, children: [_jsx(Plus, { className: "size-4 shrink-0", "aria-hidden": true }), _jsxs("span", { className: "truncate", children: [createFooterLabel ? createFooterLabel(trimmed) : `Crear ${entityLabel}`.trim(), !createFooterLabel && trimmed ? _jsxs("span", { className: "text-muted-foreground", children: [" \u00AB", trimmed, "\u00BB"] }) : null] })] })] })) : null] })] }));
+    const contentStyle = {
+        width: `max(var(--radix-popover-trigger-width), ${minListWidth})`,
+        maxWidth: 'calc(100vw - 1rem)',
+        zIndex: RECORD_PICKER_Z_INDEX,
+    };
+    const joined = !hideJoinedAction && !readOnly && hasRecordPickerAction(hasValue, onCreate, onEdit);
+    const action = joined ? (_jsx(RecordPickerAction, { hasValue: hasValue, label: entityLabel, onCreate: onCreate ? () => runCreate() : undefined, onEdit: onEdit, createLabel: createLabel, editLabel: editLabel, disabled: disabled, variant: variant })) : null;
+    const defaultValueNode = (item) => item ? (_jsxs(_Fragment, { children: [renderLead?.(item, 'value'), _jsx("span", { className: "min-w-0 flex-1 truncate", children: getLabel(item) }), renderTrailing?.(item, 'value')] })) : (_jsx("span", { className: "min-w-0 flex-1 truncate text-muted-foreground", children: placeholder }));
+    const valueNode = renderValue ? renderValue(single) : defaultValueNode(single);
+    const wrap = (row) => below ? (_jsxs("div", { className: cx('w-full min-w-0 space-y-1.5', className), "data-slot": slot, children: [row, below] })) : (row);
+    const rowClass = cx('flex w-full min-w-0 items-center gap-1.5', !below && className);
+    const rowSlot = below ? undefined : slot;
+    // ---- read-only --------------------------------------------------------
+    if (readOnly) {
+        return (_jsx(Button, { type: "button", variant: "outline", role: "combobox", id: id, disabled: true, "aria-readonly": "true", "aria-label": ariaLabel, className: cx('w-full min-w-0 cursor-default justify-start font-normal opacity-100', triggerClassName), ...triggerProps, children: _jsx("span", { className: "flex min-w-0 flex-1 items-center gap-2 text-left", children: valueNode }) }));
+    }
+    // ---- input trigger ----------------------------------------------------
+    if (isInput) {
+        const showValue = !freeText && !multiple && hasValue && !!(single || renderValue);
+        const inputCls = cx(variant === 'cell' ? 'h-8 pl-8' : 'pl-8', joined && JOINED_TRIGGER_CLASS, triggerClassName);
+        return wrap(_jsxs("div", { className: rowClass, "data-slot": rowSlot, children: [_jsxs("div", { className: "flex min-w-0 flex-1 items-stretch", children: [_jsxs(Popover, { open: listOpen, onOpenChange: (o) => !o && close(), children: [_jsx(PopoverAnchor, { asChild: true, children: _jsx("div", { ref: anchorRef, className: "relative w-full min-w-0", "data-slot": anchorSlot, children: showValue ? (_jsxs("div", { className: cx('flex min-h-9 w-full min-w-0 items-center gap-2 rounded-md border bg-background px-3 py-1.5 text-sm dark:bg-input/30', joined && 'rounded-r-none', invalid && 'border-destructive'), "data-slot": "record-picker-value", children: [Icon ? _jsx(Icon, { className: "size-4 shrink-0 text-muted-foreground", "aria-hidden": true }) : null, _jsx("div", { className: "min-w-0 flex-1", children: valueNode }), onClear && !disabled ? (_jsx(Button, { type: "button", size: "icon", variant: "ghost", className: "size-7 shrink-0", onClick: onClear, "aria-label": clearLabel, children: _jsx(X, { className: "size-4" }) })) : null] })) : (_jsxs(_Fragment, { children: [_jsx(Search, { className: cx('pointer-events-none absolute left-2.5 top-1/2 -translate-y-1/2 text-muted-foreground', variant === 'cell' ? 'size-3.5' : 'size-4'), "aria-hidden": true }), _jsx(Input, { ref: inputRef, id: id, value: query, disabled: disabled, role: "combobox", "aria-autocomplete": "list", "aria-expanded": listOpen, "aria-controls": listOpen ? listId : undefined, "aria-activedescendant": activeId, "aria-label": ariaLabel, "aria-invalid": invalid || undefined, autoComplete: "off", spellCheck: false, placeholder: placeholder, className: inputCls, onChange: (e) => {
+                                                        setQuery(e.target.value);
+                                                        setOpen(true);
+                                                    }, onBlur: () => close(), onKeyDown: onKeyDown, ...triggerProps })] })) }) }), _jsx(PopoverContent, { align: "start", sideOffset: 4, collisionPadding: 8, className: "p-0", "data-slot": contentSlot, 
+                                    // Focus stays in the text box: keep typing while the list shows.
+                                    onOpenAutoFocus: (e) => e.preventDefault(), 
+                                    // Esc is handled by the text box (closes the list and
+                                    // stops there, so the dialog around it stays open).
+                                    onEscapeKeyDown: (e) => e.preventDefault(), onCloseAutoFocus: (e) => e.preventDefault(), 
+                                    // Clicking the list (scrollbar included) must not blur the box.
+                                    onMouseDown: (e) => e.preventDefault(), onInteractOutside: (e) => {
+                                        if (anchorRef.current?.contains(e.target))
+                                            e.preventDefault();
+                                    }, style: contentStyle, children: list })] }), action] }), after] }));
+    }
+    // ---- button trigger ---------------------------------------------------
+    const onTriggerKeyDown = (e) => {
+        if (disabled)
+            return;
+        if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || (multiple && (e.key === 'Enter' || e.key === ' '))) {
+            e.preventDefault();
+            setOpen(true);
+            return;
+        }
+        // Type-to-search: a printable key on the closed trigger opens the list
+        // with that character already in the search box.
+        if (!open && e.key.length === 1 && e.key !== ' ' && !e.ctrlKey && !e.metaKey && !e.altKey) {
+            e.preventDefault();
+            setQuery(e.key);
+            setOpen(true);
+        }
+    };
+    const clearable = !!onClear && hasValue && !disabled && !multiple;
+    const cellCls = 'h-8 border-transparent bg-transparent px-2 shadow-none hover:border-input hover:bg-transparent dark:bg-transparent dark:hover:bg-transparent';
+    const comboboxAria = {
+        role: 'combobox',
+        'aria-expanded': listOpen,
+        'aria-haspopup': 'listbox',
+        'aria-controls': listOpen ? listId : undefined,
+        'aria-invalid': invalid || undefined,
+        'aria-label': ariaLabel,
+        id,
+    };
+    const triggerEl = multiple ? (_jsxs("div", { ...comboboxAria, ref: (el) => {
+            triggerRef.current = el;
+        }, tabIndex: disabled ? -1 : 0, "aria-disabled": disabled || undefined, onKeyDown: onTriggerKeyDown, className: cx('flex min-h-9 w-full min-w-0 cursor-pointer items-center justify-between gap-2 rounded-md border border-input bg-transparent px-3 py-1.5 text-sm shadow-xs outline-none transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 dark:bg-input/30', variant === 'cell' && 'min-h-8 border-transparent shadow-none', invalid && 'border-destructive ring-1 ring-destructive/30', disabled && 'pointer-events-none opacity-50', joined && JOINED_TRIGGER_CLASS, triggerClassName), "data-empty": !hasValue, ...triggerProps, children: [_jsx("span", { className: "flex min-w-0 flex-1 flex-wrap items-center gap-1", children: selectedList.length > 0 ? (selectedList.map((item) => (_jsxs(Badge, { variant: "secondary", className: "max-w-full gap-1 pr-1 font-normal", "data-slot": "record-picker-chip", children: [_jsx("span", { className: "truncate", children: getLabel(item) }), onRemove && !disabled ? (_jsx("button", { type: "button", "aria-label": `Quitar ${getLabel(item)}`, className: "rounded-full p-0.5 text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring", onPointerDown: (e) => e.stopPropagation(), onClick: (e) => {
+                                e.stopPropagation();
+                                onRemove(item);
+                            }, onKeyDown: (e) => e.stopPropagation(), children: _jsx(X, { className: "size-3" }) })) : null] }, getKey(item))))) : (_jsx("span", { className: "truncate text-muted-foreground", children: placeholder })) }), _jsx(ChevronsUpDown, { className: "size-4 shrink-0 opacity-50", "aria-hidden": true })] })) : (_jsxs(Button, { ...comboboxAria, ref: (el) => {
+            triggerRef.current = el;
+        }, type: "button", variant: "outline", disabled: disabled, onKeyDown: onTriggerKeyDown, className: cx('w-full min-w-0 flex-1 justify-between gap-2 font-normal', variant === 'cell' && cellCls, clearable && 'pr-14', joined && JOINED_TRIGGER_CLASS, invalid && 'border-destructive ring-1 ring-destructive/30', triggerClassName), "data-empty": !hasValue, ...triggerProps, children: [Icon ? _jsx(Icon, { className: "size-4 shrink-0 text-muted-foreground", "aria-hidden": true }) : null, _jsx("span", { className: "flex min-w-0 flex-1 items-center gap-2 text-left", children: valueNode }), _jsx(ChevronsUpDown, { className: "size-4 shrink-0 opacity-50", "aria-hidden": true })] }));
+    return wrap(_jsxs("div", { className: rowClass, "data-slot": rowSlot, children: [_jsxs("div", { className: "flex min-w-0 flex-1 items-center", children: [_jsxs("div", { className: "relative flex min-w-0 flex-1 items-center", children: [_jsxs(Popover, { open: listOpen, onOpenChange: (o) => (disabled ? undefined : setOpen(o)), children: [_jsx(PopoverTrigger, { asChild: true, children: triggerEl }), _jsxs(PopoverContent, { align: "start", sideOffset: 4, collisionPadding: 8, className: "p-0", "data-slot": contentSlot, style: contentStyle, onCloseAutoFocus: (e) => {
+                                            if (!tabbingRef.current)
+                                                return;
+                                            tabbingRef.current = false;
+                                            e.preventDefault();
+                                            focusNextAfter(triggerRef.current);
+                                        }, children: [_jsxs("div", { className: "flex h-10 items-center gap-2 border-b px-3", "data-slot": "record-picker-search", children: [_jsx(Search, { className: "size-4 shrink-0 opacity-50", "aria-hidden": true }), _jsx("input", { role: "combobox", "aria-expanded": listOpen, "aria-controls": listId, "aria-autocomplete": "list", "aria-activedescendant": activeId, "aria-label": searchPlaceholder, autoComplete: "off", spellCheck: false, placeholder: searchPlaceholder, value: query, onChange: (e) => setQuery(e.target.value), onKeyDown: onKeyDown, className: "flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-hidden placeholder:text-muted-foreground" })] }), list] })] }), clearable ? (_jsx("button", { type: "button", "aria-label": clearLabel, title: clearLabel, onClick: (e) => {
+                                    e.stopPropagation();
+                                    onClear?.();
+                                }, className: "absolute right-8 top-1/2 z-10 -translate-y-1/2 rounded-sm p-0.5 text-muted-foreground outline-none hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring", "data-slot": "record-picker-clear", children: _jsx(X, { className: "size-3.5" }) })) : null] }), action] }), after] }));
+}

package/dist/use-option-ids.d.ts

@@ -0,0 +1,34 @@
+import { type ResolvedOption } from './use-options-resolver';
+export type OptionIdResolution = {
+    status: 'found';
+    option: ResolvedOption;
+}
+/** The host resolved the ids and this one is not there (deleted, or not visible). */
+ | {
+    status: 'missing';
+}
+/** Could not tell (old host, error): show the raw value. */
+ | {
+    status: 'unknown';
+};
+/** Ids the kernel accepts per request (dynamic.MaxOptionsIDs). */
+export declare const OPTION_IDS_CHUNK = 100;
+export interface UseResolveOptionIdsArgs {
+    /** FK target: `/options/<ref>`. */
+    ref?: string;
+    /** Explicit options endpoint (wins over `ref`), as in useOptionsResolver. */
+    endpoint?: string;
+    /** `?field=`; defaults to `id` with a `ref`. */
+    field?: string;
+    /** Ids to label. Pass only those not already loaded / seeded. */
+    ids: readonly (string | number)[];
+    enabled?: boolean;
+}
+export interface UseResolveOptionIdsResult {
+    /** Settled resolutions by id (as given, stringified). */
+    resolved: ReadonlyMap<string, OptionIdResolution>;
+    /** Some id is still being resolved. */
+    loading: boolean;
+}
+export declare function useResolveOptionIds(args: UseResolveOptionIdsArgs): UseResolveOptionIdsResult;
+//# sourceMappingURL=use-option-ids.d.ts.map

package/dist/use-option-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-option-ids.d.ts","sourceRoot":"","sources":["../src/use-option-ids.ts"],"names":[],"mappings":"AAuBA,OAAO,EAA0D,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAEpH,MAAM,MAAM,kBAAkB,GACxB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE;AAC7C,qFAAqF;GACnF;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE;AACvB,4DAA4D;GAC1D;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAA;AAE3B,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,MAAM,CAAA;AA8EnC,MAAM,WAAW,uBAAuB;IACpC,mCAAmC;IACnC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,GAAG,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;IACjC,OAAO,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,yBAAyB;IACtC,yDAAyD;IACzD,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;IACjD,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAA;CACnB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,yBAAyB,CAqC5F"}

package/dist/use-option-ids.js

@@ -0,0 +1,138 @@
+// useResolveOptionIds — labels for values a picker already holds.
+//
+// A RecordPicker editing a saved record (a product with its brand) holds an id
+// whose label is in no loaded page: options load only once the popover opens,
+// so the trigger used to show the raw UUID unless the caller had a seed (the
+// relation sibling the table served). This hook asks the canonical options
+// endpoint for exactly those ids:
+//
+//   GET /api/options/<ref>?field=id&ids=a,b
+//
+// - One react-query entry per (org/branch, endpoint, field, id): two pickers
+//   on the same value share it, and nothing is refetched for 30 s.
+// - Every id requested within a few ms for the same endpoint + field travels in
+//   ONE request (a column of cells, a multi-select's chips), chunked at the
+//   kernel's 100-id cap.
+// - A host that predates `ids` ignores the parameter and answers a first page.
+//   The answer is then filtered by id: a hit still resolves, a miss stays
+//   `unknown` (the caller shows the value as before) instead of being reported
+//   as deleted. A response that only holds requested ids is a host that
+//   understood `ids`, so a requested id absent from it is `missing`.
+import { useContext, useMemo } from 'react';
+import { QueryClient, QueryClientContext, useQueries } from '@tanstack/react-query';
+import { useApi } from './api-context';
+import { onOptionsCacheInvalidated, optionsScope, projectOption } from './use-options-resolver';
+/** Ids the kernel accepts per request (dynamic.MaxOptionsIDs). */
+export const OPTION_IDS_CHUNK = 100;
+const OPTION_IDS_TTL_MS = 30_000;
+const OPTION_IDS_WINDOW_MS = 5;
+const QUERY_ROOT = 'metacore-option-ids';
+// Hosts without a QueryClientProvider still get dedup + cache.
+let fallbackClient = null;
+function getFallbackClient() {
+    if (!fallbackClient)
+        fallbackClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    return fallbackClient;
+}
+const knownClients = new Set();
+onOptionsCacheInvalidated(() => {
+    for (const client of knownClients)
+        void client.invalidateQueries({ queryKey: [QUERY_ROOT] });
+});
+const pendingBatches = new Map();
+function enqueue(api, scope, url, field, id) {
+    const key = [scope, url, field].join('\n');
+    // Keyed without the client: useApi() hands each component its own wrapper
+    // of the same host client, and pickers of one ref must share the request.
+    let batch = pendingBatches.get(key);
+    if (!batch) {
+        batch = { api, url, field, waiters: new Map() };
+        pendingBatches.set(key, batch);
+        const flushing = batch;
+        setTimeout(() => {
+            if (pendingBatches.get(key) === flushing)
+                pendingBatches.delete(key);
+            void flush(flushing);
+        }, OPTION_IDS_WINDOW_MS);
+    }
+    const target = batch;
+    return new Promise((resolve) => {
+        const list = target.waiters.get(id) ?? [];
+        list.push({ resolve });
+        target.waiters.set(id, list);
+    });
+}
+async function flush(batch) {
+    const ids = [...batch.waiters.keys()];
+    for (let i = 0; i < ids.length; i += OPTION_IDS_CHUNK) {
+        const chunk = ids.slice(i, i + OPTION_IDS_CHUNK);
+        const result = await fetchIds(batch.api, batch.url, batch.field, chunk);
+        for (const id of chunk) {
+            const r = result.get(id) ?? { status: 'unknown' };
+            for (const w of batch.waiters.get(id) ?? [])
+                w.resolve(r);
+        }
+    }
+}
+async function fetchIds(api, url, field, ids) {
+    const out = new Map();
+    try {
+        const res = await api.get(url, { params: { field, ids: ids.join(',') } });
+        const body = res?.data;
+        if (!body || body.success !== true || !Array.isArray(body.data))
+            return out;
+        const options = body.data.map(projectOption);
+        const byId = new Map();
+        for (const o of options)
+            byId.set(String(o.id).toLowerCase(), o);
+        const asked = new Set(ids.map((id) => id.toLowerCase()));
+        // Only requested ids back → the host honoured `ids`.
+        const honoured = options.every((o) => asked.has(String(o.id).toLowerCase()));
+        for (const id of ids) {
+            const hit = byId.get(id.toLowerCase());
+            if (hit)
+                out.set(id, { status: 'found', option: hit });
+            else if (honoured)
+                out.set(id, { status: 'missing' });
+        }
+    }
+    catch {
+        // Network / permission error: leave every id `unknown`.
+    }
+    return out;
+}
+export function useResolveOptionIds(args) {
+    const { ref, endpoint, field, ids, enabled = true } = args;
+    const api = useApi();
+    const contextClient = useContext(QueryClientContext);
+    const client = contextClient ?? getFallbackClient();
+    knownClients.add(client);
+    const url = endpoint || (ref ? `/options/${ref}` : '');
+    const effectiveField = field || (ref ? 'id' : '');
+    const scope = optionsScope();
+    const list = useMemo(() => [...new Set(ids.map(String).filter((id) => id !== ''))], [ids.map(String).join('\u0001')]);
+    const active = enabled && !!url && !!effectiveField && list.length > 0;
+    const results = useQueries({
+        queries: (active ? list : []).map((id) => ({
+            queryKey: [QUERY_ROOT, scope, url, effectiveField, id],
+            queryFn: () => enqueue(api, scope, url, effectiveField, id),
+            staleTime: OPTION_IDS_TTL_MS,
+            retry: false,
+            refetchOnWindowFocus: false,
+        })),
+    }, client);
+    const resolved = new Map();
+    let loading = false;
+    if (active) {
+        list.forEach((id, i) => {
+            const r = results[i];
+            if (r?.data)
+                resolved.set(id, r.data);
+            else if (r?.isError)
+                resolved.set(id, { status: 'unknown' });
+            else
+                loading = true;
+        });
+    }
+    return { resolved, loading };
+}

package/dist/use-options-resolver.d.ts

@@ -95,7 +95,11 @@ export interface UseOptionsResolverResult {
  * lists it instead of serving the previous 30 s snapshot.
  */
 export declare function invalidateOptionsCache(): void;
+/** Runs `fn` on every invalidateOptionsCache (id-label lookups drop with it). */
+export declare function onOptionsCacheInvalidated(fn: () => void): () => void;
 export declare function optionsRequestKey(scope: string, url: string, field: string, query: string, limit: number | undefined, filter: string | undefined): string;
+/** Org + branch of the host session: part of every options cache key. */
+export declare function optionsScope(): string;
 export declare function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsResolverResult;
 export declare function projectOption(raw: any): ResolvedOption;
 //# sourceMappingURL=use-options-resolver.d.ts.map

package/dist/use-options-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-options-resolver.d.ts","sourceRoot":"","sources":["../src/use-options-resolver.ts"],"names":[],"mappings":"AAcA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAG1E,MAAM,WAAW,cAAc;IAC3B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,WAAW;IACxB,oEAAoE;IACpE,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAA;IACnC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAsB;IACnC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACjC,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,IAAI,CAAA;CACtB;AAuBD;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAI7C;AAED,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,CAER;AA8BD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,wBAAwB,CAuKzF;AASD,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,cAAc,CAqBtD"}
+{"version":3,"file":"use-options-resolver.d.ts","sourceRoot":"","sources":["../src/use-options-resolver.ts"],"names":[],"mappings":"AAcA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAG1E,MAAM,WAAW,cAAc;IAC3B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,WAAW;IACxB,oEAAoE;IACpE,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAA;IACnC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAsB;IACnC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACjC,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,IAAI,CAAA;CACtB;AAuBD;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAK7C;AAID,iFAAiF;AACjF,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAGpE;AAED,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,CAER;AAED,yEAAyE;AACzE,wBAAgB,YAAY,IAAI,MAAM,CAWrC;AAiBD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,wBAAwB,CAuKzF;AASD,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,cAAc,CAqBtD"}

package/dist/use-options-resolver.js

@@ -40,11 +40,20 @@ export function invalidateOptionsCache() {
     optionsGeneration++;
     optionsCache.clear();
     optionsInflight.clear();
+    for (const fn of invalidationListeners)
+        fn();
+}
+const invalidationListeners = new Set();
+/** Runs `fn` on every invalidateOptionsCache (id-label lookups drop with it). */
+export function onOptionsCacheInvalidated(fn) {
+    invalidationListeners.add(fn);
+    return () => invalidationListeners.delete(fn);
 }
 export function optionsRequestKey(scope, url, field, query, limit, filter) {
     return [scope, url, field, query, String(limit ?? ''), filter ?? ''].join('\n');
 }
-function optionsScope() {
+/** Org + branch of the host session: part of every options cache key. */
+export function optionsScope() {
     if (typeof localStorage === 'undefined')
         return '';
     let org = '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "49.5.0",
+  "version": "49.7.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",

package/src/__tests__/business-pickers.test.tsx

@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 // #1025 VehiclePicker, #1026 RelateDocuments, #1027 PrintSendDialog.
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
 
 vi.mock('react-i18next', () => ({
     useTranslation: () => ({ t: (k: string, o?: any) => o?.defaultValue ?? k, i18n: { language: 'es' } }),
@@ -49,7 +49,9 @@ describe('VehiclePicker', () => {
         fireEvent.change(screen.getByPlaceholderText('Placa o VIN'), { target: { value: 'ABC' } })
         const opt = await screen.findByRole('option')
         expect(search.mock.calls[0][0]).toBe('ABC')
-        fireEvent.click(opt.querySelector('button')!)
+        // La opción misma es el elemento interactivo (RecordPicker: role=option
+        // sin <button> anidado, como pide ARIA para listbox).
+        fireEvent.click(opt)
         expect(onChange).toHaveBeenCalledWith(veh)
     })
 
@@ -102,7 +104,8 @@ describe('RelateDocuments', () => {
         const { rerender } = render(<RelateDocuments value={value} onChange={onChange} relationTypes={types} search={search} />)
         fireEvent.change(screen.getByPlaceholderText('Buscar por folio o UUID'), { target: { value: 'A-' } })
         const list = await screen.findByRole('listbox')
-        fireEvent.click(list.querySelectorAll('button')[0])
+        // RecordPicker: se elige la opción (role=option), no un <button> interno.
+        fireEvent.click((await within(list).findAllByRole('option'))[0]!)
         expect(onChange).toHaveBeenLastCalledWith([
             expect.objectContaining({ related_document_id: 'd1', relation_type: '01', uuid: 'UUID-1', folio: 'A-1' }),
         ])