@asteby/metacore-runtime-react 49.5.0 → 49.6.0

package/src/entity-select.tsx

@@ -1,5 +1,9 @@
 // EntitySelect — the shared, permission-aware single-select for a related model.
 //
+// Now a thin configuration of <RecordPicker> (record-picker.tsx); prefer it for
+// new screens. Kept with its exact props for consumers (POS, collections and
+// other federated addons).
+//
 // A searchable async combobox over a kernel model's records, plus the two
 // affordances every "pick a related record" control should have, exactly like
 // the dynamic create modal's relation fields (Categoría/Marca) do:
@@ -14,23 +18,11 @@
 // `/metadata/modal/:model` schema via <CreateRecordDialog>, so no per-model form
 // code is needed. This lives in the SDK so POS, purchases and any future addon
 // share ONE implementation instead of each re-porting a bespoke picker.
-import { useCallback, useEffect, useState } from 'react'
-import { Search, X, type LucideIcon } from 'lucide-react'
-import {
-    Button,
-    Command,
-    CommandGroup,
-    CommandInput,
-    CommandItem,
-    CommandList,
-    Popover,
-    PopoverContent,
-    PopoverTrigger,
-} from '@asteby/metacore-ui'
-import { CreateRecordDialog } from './dialogs/create-record-dialog'
-import { JOINED_TRIGGER_CLASS, PickerCreateItem, RecordPickerAction, hasRecordPickerAction } from './record-picker-actions'
+import type { LucideIcon } from 'lucide-react'
+import { RecordPicker, useLatestSearch } from './record-picker'
+import { recordLabel } from './record-picker-actions'
+import { useRecordPickerDialog } from './record-picker-dialog'
 import { useCan } from './permissions-context'
-import { useApi } from './api-context'
 
 /** One searchable option: `value` is the id, `label` the display text. */
 export interface EntitySelectOption {
@@ -96,13 +88,16 @@ function capabilityNamespace(model: string): string {
     return model.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()
 }
 
+/**
+ * @deprecated Thin wrapper over {@link RecordPicker}; prefer it for new code.
+ */
 export function EntitySelect({
     model,
     value,
     label,
     onSelect,
     fetcher,
-    icon: Icon,
+    icon,
     placeholder = 'Seleccionar…',
     searchPlaceholder = 'Buscar…',
     emptyText = 'Sin resultados',
@@ -116,197 +111,53 @@ export function EntitySelect({
     lockedCreateFields,
 }: EntitySelectProps) {
     const can = useCan()
-    const api = useApi()
-
     const ns = capabilityNamespace(model)
     const mayCreate = canCreate ?? can(`${ns}.create`)
     const mayEdit = canEdit ?? can(`${ns}.update`)
-    const base = endpoint ?? `/data/${model}/me`
-
-    const [open, setOpen] = useState(false)
-    const [dialogOpen, setDialogOpen] = useState(false)
-    const [dialogRecordId, setDialogRecordId] = useState<string | undefined>(undefined)
-    const [searchTerm, setSearchTerm] = useState('')
-    const [results, setResults] = useState<EntitySelectOption[]>([])
-    const [isLoading, setIsLoading] = useState(false)
-
-    const minChars = preload ? 0 : 2
 
-    const run = useCallback(
-        async (q: string, signal: AbortSignal) => {
-            if (q.length < minChars) {
-                setResults([])
-                return
-            }
-            setIsLoading(true)
-            try {
-                const rows = await fetcher(q, signal)
-                if (!signal.aborted) setResults(rows)
-            } catch {
-                if (!signal.aborted) setResults([])
-            } finally {
-                if (!signal.aborted) setIsLoading(false)
-            }
+    // Read the {id,label} off a saved record and select it (create) or
+    // refresh its label (edit).
+    const { openCreate, openEdit, dialog } = useRecordPickerDialog({
+        model,
+        endpoint,
+        prefillField: labelField,
+        createDefaults,
+        lockedCreateFields,
+        onSaved: (rec) => {
+            const id = rec.id != null ? String(rec.id) : value ?? ''
+            onSelect(id, recordLabel(rec, labelField) ?? label ?? id)
         },
-        [fetcher, minChars],
-    )
-
-    useEffect(() => {
-        if (!open) return
-        const controller = new AbortController()
-        const timeout = setTimeout(() => run(searchTerm, controller.signal), 250)
-        return () => {
-            clearTimeout(timeout)
-            controller.abort()
-        }
-    }, [searchTerm, run, open])
-
-    const pick = (row: EntitySelectOption) => {
-        onSelect(row.value, row.label)
-        setOpen(false)
-        setSearchTerm('')
-    }
-
-    const clear = (e: React.MouseEvent) => {
-        e.stopPropagation()
-        onSelect(null, null)
-    }
-
-    const openCreate = () => {
-        setOpen(false)
-        setDialogRecordId(undefined)
-        setDialogOpen(true)
-    }
-    const openEdit = () => {
-        if (!value) return
-        setOpen(false)
-        setDialogRecordId(value)
-        setDialogOpen(true)
-    }
-
-    // Read the {id,label} off a saved record and select it. The transport
-    // matches the standard org-scoped CRUD the dynamic modal uses, so create/edit
-    // stay consistent with the rest of the app.
-    const selectSaved = (rec: Record<string, unknown> | undefined | null) => {
-        if (!rec) return
-        const id = rec.id != null ? String(rec.id) : value ?? ''
-        const lbl =
-            (rec[labelField] != null && String(rec[labelField])) ||
-            (rec.name != null && String(rec.name)) ||
-            label ||
-            id
-        onSelect(id, lbl)
-    }
-
-    const onCreate = mayCreate ? openCreate : undefined
-    const onEdit = mayEdit ? openEdit : undefined
-    const joined = hasRecordPickerAction(!!value, onCreate, onEdit)
+    })
+    const search = useLatestSearch(fetcher)
 
     return (
-        <div className="flex items-center" data-slot="entity-select">
-            <Popover open={open} onOpenChange={disabled ? undefined : setOpen}>
-                <PopoverTrigger asChild>
-                    <Button
-                        variant="outline"
-                        disabled={disabled}
-                        className={'w-full min-w-0 flex-1 justify-start gap-2 font-normal' + (joined ? ` ${JOINED_TRIGGER_CLASS}` : '')}
-                    >
-                        {Icon && <Icon className="text-muted-foreground size-4 shrink-0" />}
-                        <span className="flex-1 truncate text-left">{label ?? placeholder}</span>
-                        {value && (
-                            <span
-                                role="button"
-                                tabIndex={0}
-                                onClick={clear}
-                                onKeyDown={(e) => {
-                                    if (e.key === 'Enter' || e.key === ' ')
-                                        clear(e as unknown as React.MouseEvent)
-                                }}
-                                className="hover:bg-accent ml-auto shrink-0 rounded-sm p-0.5"
-                            >
-                                <X className="size-3.5" />
-                            </span>
-                        )}
-                    </Button>
-                </PopoverTrigger>
-                <PopoverContent
-                    className="p-0"
-                    align="start"
-                    collisionPadding={8}
-                    style={{ width: 'max(var(--radix-popover-trigger-width), 14rem)', maxWidth: 'calc(100vw - 1rem)' }}
-                >
-                    <Command shouldFilter={false}>
-                        <CommandInput
-                            placeholder={searchPlaceholder}
-                            value={searchTerm}
-                            onValueChange={setSearchTerm}
-                        />
-                        <CommandList>
-                            {isLoading && (
-                                <div className="text-muted-foreground py-4 text-center text-sm">
-                                    Buscando…
-                                </div>
-                            )}
-                            {!isLoading &&
-                                searchTerm.length >= minChars &&
-                                results.length === 0 && <div className="text-muted-foreground py-6 text-center text-sm">{emptyText}</div>}
-                            {!isLoading && results.length > 0 && (
-                                <CommandGroup className="max-h-64 overflow-auto">
-                                    {results.map((row) => (
-                                        <CommandItem
-                                            key={row.value}
-                                            value={row.value}
-                                            onSelect={() => pick(row)}
-                                            className="flex flex-col items-start gap-0.5"
-                                        >
-                                            <span className="text-sm font-medium">{row.label}</span>
-                                            {row.description && (
-                                                <span className="text-muted-foreground text-xs">
-                                                    {row.description}
-                                                </span>
-                                            )}
-                                        </CommandItem>
-                                    ))}
-                                </CommandGroup>
-                            )}
-                            {!isLoading && !preload && searchTerm.length < minChars && (
-                                <div className="text-muted-foreground flex flex-col items-center gap-1 py-6">
-                                    <Search className="size-5" />
-                                    <span className="text-xs">Escribe al menos 2 caracteres</span>
-                                </div>
-                            )}
-                            {onCreate && !isLoading && <PickerCreateItem label={model} onSelect={openCreate} />}
-                        </CommandList>
-                    </Command>
-                </PopoverContent>
-            </Popover>
-
-            {/* Selected → edit (pencil); empty → create (+). Each gated by perms. */}
-            <RecordPickerAction hasValue={!!value} label={model} onCreate={onCreate} onEdit={onEdit} disabled={disabled} />
-
-            {dialogOpen && (
-                <CreateRecordDialog
-                    modelKey={model}
-                    open={dialogOpen}
-                    onOpenChange={setDialogOpen}
-                    recordId={dialogRecordId}
-                    endpoint={base}
-                    defaults={dialogRecordId ? undefined : createDefaults}
-                    lockedFields={dialogRecordId ? undefined : lockedCreateFields}
-                    onCreate={async (data) => {
-                        const res = await api.post(base, data)
-                        const rec = (res.data?.data ?? res.data) as Record<string, unknown>
-                        selectSaved(rec)
-                        return rec.id != null ? { id: String(rec.id) } : undefined
-                    }}
-                    onUpdate={async (id, data) => {
-                        const res = await api.put(`${base}/${id}`, data)
-                        const rec = (res.data?.data ?? res.data) as Record<string, unknown>
-                        selectSaved({ id, ...rec })
-                        return { id: String(id) }
-                    }}
-                />
-            )}
-        </div>
+        <>
+            <RecordPicker<EntitySelectOption>
+                slot="entity-select"
+                search={search}
+                minChars={preload ? 0 : 2}
+                minCharsText="Escribe al menos 2 caracteres"
+                getKey={(o) => o.value}
+                getLabel={(o) => o.label}
+                getDescription={(o) => o.description}
+                showCheck={false}
+                value={value}
+                selected={value ? { value, label: label ?? value } : null}
+                onSelect={(o) => onSelect(o.value, o.label)}
+                onClear={() => onSelect(null, null)}
+                icon={icon}
+                placeholder={placeholder}
+                renderValue={(sel) => (
+                    <span className={'min-w-0 flex-1 truncate' + (sel ? '' : ' text-muted-foreground')}>{label ?? placeholder}</span>
+                )}
+                searchPlaceholder={searchPlaceholder}
+                emptyText={emptyText}
+                entityLabel={model}
+                onCreate={mayCreate ? (q) => openCreate(q) : undefined}
+                onEdit={mayEdit && value ? () => openEdit(value) : undefined}
+                disabled={disabled}
+            />
+            {dialog}
+        </>
     )
 }

package/src/index.ts

@@ -475,8 +475,33 @@ export type { DynamicRecordDialogProps, FieldDef, FieldOption, GetImageUrl } fro
 export { CreateRecordDialog } from './dialogs/create-record-dialog'
 export { EntitySelect } from './entity-select'
 export type { EntitySelectProps, EntitySelectOption } from './entity-select'
-export { RecordPickerAction, PickerCreateItem, JOINED_TRIGGER_CLASS, hasRecordPickerAction } from './record-picker-actions'
-export type { RecordPickerActionProps } from './record-picker-actions'
+// RecordPicker — the ONE "pick a related record" control (search, single /
+// multiple, create / edit, rich options, field / cell, portaled list). Every
+// picker above (DynamicSelectField, EntitySelect, Customer/Product/Vehicle
+// pickers, LineProductCell) is a thin configuration of it.
+export { RecordPicker, useRecordSearch, useLatestSearch, RECORD_PICKER_Z_INDEX } from './record-picker'
+export type {
+    RecordPickerProps,
+    RecordPickerItemState,
+    RecordPickerVariant,
+    RecordPickerTrigger,
+    UseRecordSearchOptions,
+    UseRecordSearchResult,
+} from './record-picker'
+export {
+    RecordPickerAction,
+    PickerCreateItem,
+    JOINED_TRIGGER_CLASS,
+    hasRecordPickerAction,
+    requestRecordCreate,
+    requestRecordEdit,
+    recordLabel,
+    withSearchPrefill,
+} from './record-picker-actions'
+export type { RecordPickerActionProps, RecordCreateRequest, RecordEditRequest } from './record-picker-actions'
+export { useRecordPickerDialog } from './record-picker-dialog'
+export type { UseRecordPickerDialogOptions, UseRecordPickerDialogResult } from './record-picker-dialog'
+export { OptionLead, OptionThumb } from './record-picker-option'
 export { ViewRecordDialog } from './dialogs/view-record-dialog'
 export type {
     ModelKey,

package/src/record-picker-actions.tsx

@@ -1,16 +1,21 @@
-// RecordPickerActions — create/edit affordances shared by every "pick a related
-// record" control (DynamicSelectField for declarative forms, EntitySelect for
-// hand-written screens). ONE implementation of the same contract:
+// RecordPickerActions — create/edit affordances of the shared <RecordPicker>
+// (record-picker.tsx), the ONE "pick a related record" control of the runtime.
+// Every picker (DynamicSelectField, EntitySelect, the business pickers) gets
+// the same contract from here:
 //
 //   - nothing selected → "+" joined to the trigger: opens the model's CREATE
 //     modal and the new record ends up selected;
 //   - a record selected → pencil joined to the trigger: opens THAT record's
 //     EDIT modal and the label refreshes on save;
 //   - "Crear …" at the foot of the result list, so creating is one step away
-//     from a search with no hits.
+//     from a search with no hits (prefilled with the searched text).
 //
 // The action renders as a segment of the trigger (shared border, no gap) so the
 // control reads as a single field instead of a select plus a loose button.
+//
+// The create/edit modals themselves are the HOST's (decoupled window events the
+// host's RecordCreateBridge listens for) or, for hand-written screens, the
+// in-tree <CreateRecordDialog> (see record-picker-dialog.tsx).
 import type { ReactNode } from 'react'
 import { Pencil, Plus } from 'lucide-react'
 import { Button, CommandGroup, CommandItem, CommandSeparator } from '@asteby/metacore-ui/primitives'
@@ -26,6 +31,13 @@ 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
 }
 
 /**
@@ -33,11 +45,22 @@ export interface RecordPickerActionProps {
  * 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 }: RecordPickerActionProps) {
+export function RecordPickerAction({
+    hasValue,
+    label,
+    onCreate,
+    onEdit,
+    disabled,
+    createLabel,
+    editLabel,
+    variant = 'field',
+    className,
+}: RecordPickerActionProps) {
     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 (
         <Button
             type="button"
@@ -53,7 +76,10 @@ export function RecordPickerAction({ hasValue, label, onCreate, onEdit, disabled
             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"
+            className={
+                `-ml-px ${size} shrink-0 rounded-l-none text-muted-foreground hover:text-foreground focus-visible:z-10` +
+                (className ? ` ${className}` : '')
+            }
         >
             {edit ? <Pencil className="size-4" /> : <Plus className="size-4" />}
         </Button>
@@ -65,7 +91,12 @@ export function hasRecordPickerAction(hasValue: boolean, onCreate?: unknown, onE
     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 }: { label: string; onSelect: () => void; children?: ReactNode }) {
     return (
         <>
@@ -79,3 +110,65 @@ export function PickerCreateItem({ label, onSelect, children }: { label: string;
         </>
     )
 }
+
+// ---------------------------------------------------------------------------
+// Host create/edit modal — decoupled window events.
+//
+// The SDK never imports host code: a picker fires `metacore:create-record` /
+// `metacore:edit-record` and the host's RecordCreateBridge opens the model's
+// REAL modal (full fields from /metadata/modal), handing the saved record back
+// through the callback. Works for ANY model.
+// ---------------------------------------------------------------------------
+
+/** 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 function requestRecordCreate(req: RecordCreateRequest): void {
+    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: RecordEditRequest): void {
+    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: Record<string, unknown> | null | undefined, labelField = 'name'): string | undefined {
+    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: string | undefined,
+    field: string | null | undefined,
+    defaults?: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+    const q = (query ?? '').trim()
+    if (!q || !field) return defaults
+    return { [field]: q, ...(defaults ?? {}) }
+}

package/src/record-picker-dialog.tsx

@@ -0,0 +1,80 @@
+// 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, type ReactNode } from 'react'
+import { CreateRecordDialog } from './dialogs/create-record-dialog'
+import { useApi } from './api-context'
+import { withSearchPrefill } from './record-picker-actions'
+
+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
+}
+
+const unwrap = (res: { data?: any }) => ((res.data?.data ?? res.data) ?? {}) as Record<string, unknown>
+
+export function useRecordPickerDialog({
+    model,
+    endpoint,
+    prefillField = 'name',
+    createDefaults,
+    lockedCreateFields,
+    onSaved,
+}: UseRecordPickerDialogOptions): UseRecordPickerDialogResult {
+    const api = useApi()
+    const base = endpoint ?? `/data/${model}/me`
+    const [state, setState] = useState<{ recordId?: string; defaults?: Record<string, unknown> } | null>(null)
+
+    const dialog = state ? (
+        <CreateRecordDialog
+            modelKey={model}
+            open
+            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: string) => setState({ recordId: id }),
+        dialog,
+    }
+}

package/src/record-picker-option.tsx

@@ -0,0 +1,96 @@
+// 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'
+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 function OptionThumb({
+    image,
+    name,
+    size = 20,
+}: {
+    image?: string | null
+    name?: string | null
+    size?: number
+}) {
+    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 <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 (
+            <span className="flex shrink-0 items-center justify-center rounded-sm bg-muted" style={box} aria-hidden>
+                <DynamicIcon name={image} className="size-4" />
+            </span>
+        )
+    }
+    return (
+        <img
+            src={image}
+            alt=""
+            aria-hidden
+            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,
+}: {
+    option?: Pick<ResolvedOption, 'image' | 'color' | 'icon' | 'label'> | null
+    size?: number
+}) {
+    if (!option) return null
+    if (option.image) return <OptionThumb image={option.image} name={option.label} size={size} />
+    if (option.icon) {
+        return (
+            <span
+                className="flex shrink-0 items-center justify-center"
+                style={{ width: size, height: size, color: option.color ? resolveColorCss(option.color) : undefined }}
+                aria-hidden
+            >
+                <DynamicIcon name={option.icon} className="size-4" />
+            </span>
+        )
+    }
+    if (option.color) {
+        return (
+            <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
+            />
+        )
+    }
+    // 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 <InitialsAvatar name={option.label} size={size} rounded="sm" tone="neutral" />
+    return null
+}