@asteby/metacore-runtime-react 49.5.0 → 49.6.0

package/dist/record-picker-actions.d.ts

@@ -9,19 +9,57 @@ export interface RecordPickerActionProps {
     onCreate?: () => void;
     onEdit?: () => void;
     disabled?: boolean;
+    /** Accessible name override for the "+" (default `Crear <label>`). */
+    createLabel?: string;
+    /** Accessible name override for the pencil (default `Editar <label>`). */
+    editLabel?: string;
+    /** `cell` → compact, borderless segment for table cells. */
+    variant?: 'field' | 'cell';
+    className?: string;
 }
 /**
  * Joined trailing segment: pencil when there is a value (and `onEdit`), "+"
  * otherwise (and `onCreate`). Renders nothing when neither applies — callers
  * should then drop {@link JOINED_TRIGGER_CLASS} from the trigger.
  */
-export declare function RecordPickerAction({ hasValue, label, onCreate, onEdit, disabled }: RecordPickerActionProps): import("react").JSX.Element | null;
+export declare function RecordPickerAction({ hasValue, label, onCreate, onEdit, disabled, createLabel, editLabel, variant, className, }: RecordPickerActionProps): import("react").JSX.Element | null;
 /** True when a picker will render a joined action for the given state. */
 export declare function hasRecordPickerAction(hasValue: boolean, onCreate?: unknown, onEdit?: unknown): boolean;
-/** "Crear …" row at the foot of a Command list. */
+/**
+ * "Crear …" row at the foot of a cmdk `<Command>` list.
+ *
+ * @deprecated <RecordPicker> renders its own create footer (with the searched
+ * text prefilled). Kept for hand-written cmdk lists in consumers.
+ */
 export declare function PickerCreateItem({ label, onSelect, children }: {
     label: string;
     onSelect: () => void;
     children?: ReactNode;
 }): import("react").JSX.Element;
+/** Detail of the `metacore:create-record` event (contract with the host). */
+export interface RecordCreateRequest {
+    model: string;
+    /** Seed values for the new record. Keys that aren't fields of the model are ignored by the dialog. */
+    defaults?: Record<string, unknown>;
+    /** Fields rendered locked in the create modal. */
+    lockedFields?: string[];
+    onCreated?: (record: any) => void;
+}
+/** Detail of the `metacore:edit-record` event (contract with the host). */
+export interface RecordEditRequest {
+    model: string;
+    recordId: string;
+    onSaved?: (record: any) => void;
+}
+/** Ask the host to open `model`'s create modal. No-op outside a browser. */
+export declare function requestRecordCreate(req: RecordCreateRequest): void;
+/** Ask the host to open the edit modal of `recordId`. No-op outside a browser. */
+export declare function requestRecordEdit(req: RecordEditRequest): void;
+/** Display label of a saved record: `labelField`, else name / label / title. */
+export declare function recordLabel(rec: Record<string, unknown> | null | undefined, labelField?: string): string | undefined;
+/**
+ * Create defaults with the searched text seeded into `field` (the model's
+ * label column: name, plate…). Explicit `defaults` win over the prefill.
+ */
+export declare function withSearchPrefill(query: string | undefined, field: string | null | undefined, defaults?: Record<string, unknown>): Record<string, unknown> | undefined;
 //# sourceMappingURL=record-picker-actions.d.ts.map

package/dist/record-picker-actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record-picker-actions.d.ts","sourceRoot":"","sources":["../src/record-picker-actions.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,sCAAsC,CAAA;AAEvE,MAAM,WAAW,uBAAuB;IACpC,yDAAyD;IACzD,QAAQ,EAAE,OAAO,CAAA;IACjB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,uBAAuB,sCAyB1G;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAEtG;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,+BAY5H"}
+{"version":3,"file":"record-picker-actions.d.ts","sourceRoot":"","sources":["../src/record-picker-actions.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,sCAAsC,CAAA;AAEvE,MAAM,WAAW,uBAAuB;IACpC,yDAAyD;IACzD,QAAQ,EAAE,OAAO,CAAA;IACjB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAC/B,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,WAAW,EACX,SAAS,EACT,OAAiB,EACjB,SAAS,GACZ,EAAE,uBAAuB,sCA6BzB;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAEtG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,+BAY5H;AAWD,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,sGAAsG;IACtG,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAA;CACpC;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAA;CAClC;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAGlE;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAG9D;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,UAAU,SAAS,GAAG,MAAM,GAAG,SAAS,CAOpH;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAIrC"}

package/dist/record-picker-actions.js

@@ -8,25 +8,65 @@ export const JOINED_TRIGGER_CLASS = 'rounded-r-none focus-visible:z-10';
  * otherwise (and `onCreate`). Renders nothing when neither applies — callers
  * should then drop {@link JOINED_TRIGGER_CLASS} from the trigger.
  */
-export function RecordPickerAction({ hasValue, label, onCreate, onEdit, disabled }) {
+export function RecordPickerAction({ hasValue, label, onCreate, onEdit, disabled, createLabel, editLabel, variant = 'field', className, }) {
     const edit = hasValue && !!onEdit;
     const create = !hasValue && !!onCreate;
     if (!edit && !create)
         return null;
-    const name = edit ? `Editar ${label}` : `Crear ${label}`;
+    const name = edit ? editLabel ?? `Editar ${label}` : createLabel ?? `Crear ${label}`;
+    const size = variant === 'cell' ? 'size-8 border-transparent bg-transparent shadow-none' : 'size-9';
     return (_jsx(Button, { type: "button", variant: "outline", size: "icon", disabled: disabled, onClick: (e) => {
             e.stopPropagation();
             if (edit)
                 onEdit?.();
             else
                 onCreate?.();
-        }, "aria-label": name, title: name, "data-slot": "record-picker-action", "data-action": edit ? 'edit' : 'create', className: "-ml-px size-9 shrink-0 rounded-l-none text-muted-foreground hover:text-foreground focus-visible:z-10", children: edit ? _jsx(Pencil, { className: "size-4" }) : _jsx(Plus, { className: "size-4" }) }));
+        }, "aria-label": name, title: name, "data-slot": "record-picker-action", "data-action": edit ? 'edit' : 'create', className: `-ml-px ${size} shrink-0 rounded-l-none text-muted-foreground hover:text-foreground focus-visible:z-10` +
+            (className ? ` ${className}` : ''), children: edit ? _jsx(Pencil, { className: "size-4" }) : _jsx(Plus, { className: "size-4" }) }));
 }
 /** True when a picker will render a joined action for the given state. */
 export function hasRecordPickerAction(hasValue, onCreate, onEdit) {
     return hasValue ? !!onEdit : !!onCreate;
 }
-/** "Crear …" row at the foot of a Command list. */
+/**
+ * "Crear …" row at the foot of a cmdk `<Command>` list.
+ *
+ * @deprecated <RecordPicker> renders its own create footer (with the searched
+ * text prefilled). Kept for hand-written cmdk lists in consumers.
+ */
 export function PickerCreateItem({ label, onSelect, children }) {
     return (_jsxs(_Fragment, { children: [_jsx(CommandSeparator, {}), _jsx(CommandGroup, { children: _jsxs(CommandItem, { value: "__create__", onSelect: onSelect, "data-slot": "picker-create", className: "text-primary", children: [_jsx(Plus, { className: "mr-2 size-4 shrink-0" }), _jsx("span", { className: "truncate", children: children ?? `Crear ${label}` })] }) })] }));
 }
+/** Ask the host to open `model`'s create modal. No-op outside a browser. */
+export function requestRecordCreate(req) {
+    if (typeof window === 'undefined')
+        return;
+    window.dispatchEvent(new CustomEvent('metacore:create-record', { detail: req }));
+}
+/** Ask the host to open the edit modal of `recordId`. No-op outside a browser. */
+export function requestRecordEdit(req) {
+    if (typeof window === 'undefined')
+        return;
+    window.dispatchEvent(new CustomEvent('metacore:edit-record', { detail: req }));
+}
+/** Display label of a saved record: `labelField`, else name / label / title. */
+export function recordLabel(rec, labelField = 'name') {
+    if (!rec)
+        return undefined;
+    for (const k of [labelField, 'name', 'label', 'title']) {
+        const v = rec[k];
+        if (v != null && v !== '')
+            return String(v);
+    }
+    return undefined;
+}
+/**
+ * Create defaults with the searched text seeded into `field` (the model's
+ * label column: name, plate…). Explicit `defaults` win over the prefill.
+ */
+export function withSearchPrefill(query, field, defaults) {
+    const q = (query ?? '').trim();
+    if (!q || !field)
+        return defaults;
+    return { [field]: q, ...(defaults ?? {}) };
+}

package/dist/record-picker-dialog.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from 'react';
+export interface UseRecordPickerDialogOptions {
+    /** Kernel model key. */
+    model: string;
+    /** CRUD base. Default `/data/<model>/me`; edit PUTs `<base>/<id>`. */
+    endpoint?: string;
+    /** Field seeded with the searched text on create (null = none). Default "name". */
+    prefillField?: string | null;
+    /** Seed values for create (win over the prefill). */
+    createDefaults?: Record<string, unknown>;
+    /** Fields of `createDefaults` rendered locked on create. */
+    lockedCreateFields?: string[];
+    /** The saved record (`{ id, ...fields }`). */
+    onSaved: (record: Record<string, unknown>, kind: 'create' | 'edit') => void;
+}
+export interface UseRecordPickerDialogResult {
+    openCreate: (query?: string) => void;
+    openEdit: (id: string) => void;
+    /** Render it next to the picker. */
+    dialog: ReactNode;
+}
+export declare function useRecordPickerDialog({ model, endpoint, prefillField, createDefaults, lockedCreateFields, onSaved, }: UseRecordPickerDialogOptions): UseRecordPickerDialogResult;
+//# sourceMappingURL=record-picker-dialog.d.ts.map

package/dist/record-picker-dialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-picker-dialog.d.ts","sourceRoot":"","sources":["../src/record-picker-dialog.tsx"],"names":[],"mappings":"AASA,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAKhD,MAAM,WAAW,4BAA4B;IACzC,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,4DAA4D;IAC5D,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC7B,8CAA8C;IAC9C,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,KAAK,IAAI,CAAA;CAC9E;AAED,MAAM,WAAW,2BAA2B;IACxC,UAAU,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IACpC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,oCAAoC;IACpC,MAAM,EAAE,SAAS,CAAA;CACpB;AAID,wBAAgB,qBAAqB,CAAC,EAClC,KAAK,EACL,QAAQ,EACR,YAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,OAAO,GACV,EAAE,4BAA4B,GAAG,2BAA2B,CAkC5D"}

package/dist/record-picker-dialog.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// useRecordPickerDialog — create/edit plumbing for pickers on hand-written
+// screens that sit outside the host's RecordCreateBridge (POS, federated
+// panels): the in-tree, metadata-driven <CreateRecordDialog> posting to the
+// standard org-scoped CRUD (`/data/<model>/me`). Declarative pickers use the
+// host events instead (requestRecordCreate / requestRecordEdit).
+//
+// One implementation for EntitySelect, CustomerPicker and VehiclePicker: the
+// searched text prefills the new record's label field, the saved record is
+// handed back to select it (create) or refresh its label (edit).
+import { useState } from 'react';
+import { CreateRecordDialog } from './dialogs/create-record-dialog';
+import { useApi } from './api-context';
+import { withSearchPrefill } from './record-picker-actions';
+const unwrap = (res) => ((res.data?.data ?? res.data) ?? {});
+export function useRecordPickerDialog({ model, endpoint, prefillField = 'name', createDefaults, lockedCreateFields, onSaved, }) {
+    const api = useApi();
+    const base = endpoint ?? `/data/${model}/me`;
+    const [state, setState] = useState(null);
+    const dialog = state ? (_jsx(CreateRecordDialog, { modelKey: model, open: true, onOpenChange: (o) => {
+            if (!o)
+                setState(null);
+        }, recordId: state.recordId, endpoint: base, defaults: state.recordId ? undefined : state.defaults, lockedFields: state.recordId ? undefined : lockedCreateFields, onCreate: async (data) => {
+            const rec = unwrap(await api.post(base, data));
+            onSaved(rec, 'create');
+            return rec.id != null ? { id: String(rec.id) } : undefined;
+        }, onUpdate: async (id, data) => {
+            const rec = unwrap(await api.put(`${base}/${id}`, data));
+            onSaved({ ...rec, id: rec.id ?? id }, 'edit');
+            return { id: String(id) };
+        } })) : null;
+    return {
+        openCreate: (query = '') => setState({ defaults: withSearchPrefill(query, prefillField, createDefaults) }),
+        openEdit: (id) => setState({ recordId: id }),
+        dialog,
+    };
+}

package/dist/record-picker-option.d.ts

@@ -0,0 +1,25 @@
+import type { ResolvedOption } from './use-options-resolver';
+/**
+ * Small square thumbnail for an option's `image`. When the option has no image
+ * it falls back to a deterministic initials avatar (shared `InitialsAvatar`)
+ * derived from `name`, so an imageless reference reads as a colored badge rather
+ * than an empty placeholder — and rows/triggers stay aligned. `size` is in
+ * pixels (kept small — 20–24px — so the picker reads as a list, not a gallery).
+ * Inline style for the box dimensions: arbitrary Tailwind classes from a
+ * federated addon don't always survive the host's class scan.
+ */
+export declare function OptionThumb({ image, name, size, }: {
+    image?: string | null;
+    name?: string | null;
+    size?: number;
+}): import("react").JSX.Element;
+/**
+ * Leading visual for an option: a photo thumbnail (FK relations with an image),
+ * else a declared icon, else a color dot (enum/status options with a color).
+ * Returns null when the option carries none, so plain text options stay plain.
+ */
+export declare function OptionLead({ option, size, }: {
+    option?: Pick<ResolvedOption, 'image' | 'color' | 'icon' | 'label'> | null;
+    size?: number;
+}): import("react").JSX.Element | null;
+//# sourceMappingURL=record-picker-option.d.ts.map

package/dist/record-picker-option.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-picker-option.d.ts","sourceRoot":"","sources":["../src/record-picker-option.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,EACxB,KAAK,EACL,IAAI,EACJ,IAAS,GACZ,EAAE;IACC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB,+BA4BA;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EACvB,MAAM,EACN,IAAS,GACZ,EAAE;IACC,MAAM,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAA;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB,sCA4BA"}

package/dist/record-picker-option.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Option visuals shared by every RecordPicker configuration: a thumbnail
+// (image / lucide icon name / initials fallback) and the leading visual of an
+// option (image, else icon, else color dot, else initials).
+import { useState } from 'react';
+import { InitialsAvatar } from '@asteby/metacore-ui/primitives';
+import { resolveColorCss } from '@asteby/metacore-ui/lib';
+import { DynamicIcon, isLucideIconName } from './dynamic-icon';
+/**
+ * Small square thumbnail for an option's `image`. When the option has no image
+ * it falls back to a deterministic initials avatar (shared `InitialsAvatar`)
+ * derived from `name`, so an imageless reference reads as a colored badge rather
+ * than an empty placeholder — and rows/triggers stay aligned. `size` is in
+ * pixels (kept small — 20–24px — so the picker reads as a list, not a gallery).
+ * Inline style for the box dimensions: arbitrary Tailwind classes from a
+ * federated addon don't always survive the host's class scan.
+ */
+export function OptionThumb({ image, name, size = 20, }) {
+    const [broken, setBroken] = useState(false);
+    const box = { width: size, height: size };
+    // Missing or 404 image (bare avatar filenames often 404) → initials, never
+    // an invisible box that looks like "no avatar".
+    if (!image || broken) {
+        return _jsx(InitialsAvatar, { name: name, size: size, rounded: "sm", tone: "neutral" });
+    }
+    // A lucide icon name stored where an image url/path is expected (the `icon`
+    // form widget's icon mode) → render the glyph instead of a broken <img>.
+    if (isLucideIconName(image)) {
+        return (_jsx("span", { className: "flex shrink-0 items-center justify-center rounded-sm bg-muted", style: box, "aria-hidden": true, children: _jsx(DynamicIcon, { name: image, className: "size-4" }) }));
+    }
+    return (_jsx("img", { src: image, alt: "", "aria-hidden": true, loading: "lazy", className: "shrink-0 rounded-sm object-cover", style: box, onError: () => setBroken(true) }));
+}
+/**
+ * Leading visual for an option: a photo thumbnail (FK relations with an image),
+ * else a declared icon, else a color dot (enum/status options with a color).
+ * Returns null when the option carries none, so plain text options stay plain.
+ */
+export function OptionLead({ option, size = 20, }) {
+    if (!option)
+        return null;
+    if (option.image)
+        return _jsx(OptionThumb, { image: option.image, name: option.label, size: size });
+    if (option.icon) {
+        return (_jsx("span", { className: "flex shrink-0 items-center justify-center", style: { width: size, height: size, color: option.color ? resolveColorCss(option.color) : undefined }, "aria-hidden": true, children: _jsx(DynamicIcon, { name: option.icon, className: "size-4" }) }));
+    }
+    if (option.color) {
+        return (_jsx("span", { className: "shrink-0 rounded-full", style: { width: Math.round(size * 0.5), height: Math.round(size * 0.5), background: resolveColorCss(option.color) }, "aria-hidden": true }));
+    }
+    // No image/icon/color: an imageless reference option. Show its initials
+    // (shared InitialsAvatar) so it stays visually aligned with the sibling
+    // options that DO carry a thumbnail, rather than a blank gap.
+    if (option.label)
+        return _jsx(InitialsAvatar, { name: option.label, size: size, rounded: "sm", tone: "neutral" });
+    return null;
+}

package/dist/record-picker.d.ts

@@ -0,0 +1,149 @@
+import { type KeyboardEvent, type ReactNode, type Ref } from 'react';
+import { type LucideIcon } from 'lucide-react';
+/**
+ * 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 declare const RECORD_PICKER_Z_INDEX = 60;
+export interface UseRecordSearchOptions {
+    /** Characters required before searching (default 2). 0 = search on empty too. */
+    minChars?: number;
+    /** Debounce in ms (default 250). */
+    delay?: number;
+    /** When false nothing is fetched and results reset (e.g. list closed). Default true. */
+    enabled?: boolean;
+}
+export interface UseRecordSearchResult<T> {
+    results: T[];
+    /** A request is in flight. */
+    loading: boolean;
+    /** The last request failed. */
+    error: boolean;
+    /** The debounce has not caught up with the typed text yet. */
+    pending: boolean;
+}
+/** Debounced async search with cancellation. `search` must be stable (useCallback). */
+export declare function useRecordSearch<T>(query: string, search: (q: string, signal: AbortSignal) => Promise<T[]>, opts?: UseRecordSearchOptions): UseRecordSearchResult<T>;
+/**
+ * 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 declare function useLatestSearch<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R;
+export interface RecordPickerItemState {
+    /** Keyboard / pointer highlight. */
+    active: boolean;
+    /** Part of the current value. */
+    selected: boolean;
+    disabled: boolean;
+}
+export type RecordPickerVariant = 'field' | 'cell';
+export type RecordPickerTrigger = 'button' | 'input';
+export interface RecordPickerProps<T> {
+    /** Stable id of an item (the stored value). */
+    getKey: (item: T) => string;
+    /** Display text of an item. */
+    getLabel: (item: T) => string;
+    /** Caller-owned list (resolver, static options, a search the caller drives). Wins over `search`. */
+    items?: readonly T[];
+    /** Async source run here (debounced, cancelled, gated by `minChars`). Must be stable. */
+    search?: (q: string, signal: AbortSignal) => Promise<T[]>;
+    /** Characters required before searching / opening the input list. Default 0 (button) / 2 (input). */
+    minChars?: number;
+    /** Debounce for `search` (ms). Default 250. */
+    debounceMs?: number;
+    /** Loading flag for caller-owned `items`. */
+    loading?: boolean;
+    /** Error flag for caller-owned `items`. */
+    error?: boolean;
+    query?: string;
+    onQueryChange?: (query: string) => void;
+    /** Button: popover open. Input: the user is actively searching. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    multiple?: boolean;
+    /** Current value: an id (single) or ids (multiple). */
+    value?: string | number | null | readonly (string | number)[];
+    /** Resolved item(s) of the current value, for the trigger. */
+    selected?: T | readonly T[] | null;
+    /** An item was picked (in `multiple`, toggle it). */
+    onSelect: (item: T) => void;
+    /** Shows a clear (×) when there is a value. */
+    onClear?: () => void;
+    /** Chip remove in `multiple`. */
+    onRemove?: (item: T) => void;
+    /** Close after a pick. Default: true for single, false for multiple. */
+    closeOnSelect?: boolean;
+    /** Full option body override. */
+    renderItem?: (item: T, state: RecordPickerItemState) => ReactNode;
+    /** Leading visual (avatar / initials / thumbnail / icon). */
+    renderLead?: (item: T, where: 'option' | 'value') => ReactNode;
+    /** Subtitle under the label (SKU, RFC, phone…). */
+    getDescription?: (item: T) => ReactNode;
+    /** Right-aligned content (price, stock badge…). */
+    renderTrailing?: (item: T, where: 'option' | 'value') => ReactNode;
+    /** Trigger content override (button) / selected display (input). */
+    renderValue?: (selected: T | null) => ReactNode;
+    isItemDisabled?: (item: T) => boolean;
+    /** Check mark column. Default: true in button mode. */
+    showCheck?: boolean;
+    placeholder?: string;
+    searchPlaceholder?: string;
+    emptyText?: ReactNode;
+    loadingText?: ReactNode;
+    errorText?: ReactNode;
+    /** Shown below `minChars` in button mode. */
+    minCharsText?: ReactNode;
+    clearLabel?: string;
+    /** Accessible name of the listbox. */
+    listLabel?: string;
+    /** Human name of the referenced model, for "Crear …" / "Editar …". */
+    entityLabel?: string;
+    /** "+" (empty) and list footer. Receives the searched text to prefill. */
+    onCreate?: (query: string) => void;
+    /** Pencil (with a value). */
+    onEdit?: () => void;
+    createLabel?: string;
+    editLabel?: string;
+    /** When the "Crear …" footer shows: always (default), only with no hits, or never. */
+    createFooter?: 'always' | 'empty' | 'never';
+    createFooterLabel?: (query: string) => ReactNode;
+    /** Hide the joined +/pencil segment (keeps the footer). */
+    hideJoinedAction?: boolean;
+    trigger?: RecordPickerTrigger;
+    variant?: RecordPickerVariant;
+    /** Input mode: the typed text IS the value (never shows a selected display). */
+    freeText?: boolean;
+    icon?: LucideIcon;
+    id?: string;
+    ariaLabel?: string;
+    disabled?: boolean;
+    /** Locked display of the current value (no list, no actions). */
+    readOnly?: boolean;
+    invalid?: boolean;
+    /** data-slot of the root (keeps legacy hooks like `dynamic-select`). */
+    slot?: string;
+    /** data-slot of the input-mode anchor. */
+    anchorSlot?: string;
+    /** data-slot of the portaled list container. */
+    contentSlot?: string;
+    className?: string;
+    triggerClassName?: string;
+    /** Extra attributes for the trigger / text box (data-*, …). */
+    triggerProps?: Record<string, unknown>;
+    inputRef?: Ref<HTMLInputElement>;
+    /** Floor for the list width (CSS length). Default 14rem. */
+    minListWidth?: string;
+    /** Rendered after the joined group (e.g. a scan button). */
+    after?: ReactNode;
+    /** Rendered under the control (badges, hints). */
+    below?: ReactNode;
+    /** Rendered at the top of the list. */
+    beforeList?: ReactNode;
+    /** Runs first on every key in the text box; `preventDefault()` to take over. */
+    onInputKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
+    /** Keys the picker did not consume (closed list, Enter with no hits…). */
+    onUnhandledKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
+}
+export declare function RecordPicker<T>(props: RecordPickerProps<T>): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+//# sourceMappingURL=record-picker.d.ts.map

package/dist/record-picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-picker.d.ts","sourceRoot":"","sources":["../src/record-picker.tsx"],"names":[],"mappings":"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"}