@asteby/metacore-runtime-react 17.0.3 → 18.0.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @asteby/metacore-runtime-react
 
+## 18.0.0
+
+### Patch Changes
+
+- ce9dd72: `DynamicSelectField` (the searchable FK / option picker) now renders each
+  option's leading visual: a photo thumbnail (FK relations with an image), else a
+  declared icon, else a colored dot for enum/status options that carry a `color`.
+  Previously only image thumbnails showed, so enum selects (state, origin, …) read
+  as plain text. Plain options with no image/color/icon stay plain.
+- Updated dependencies [8439e9e]
+  - @asteby/metacore-ui@2.5.0
+
+## 17.0.4
+
+### Patch Changes
+
+- a745f5c: Relation/option thumbnails: resolved FK relation chips and option badges now
+  render a small thumbnail when the backend stamps an `image` on the sibling
+  `{ value, label }` object or the option (brand logo, product photo, customer
+  avatar), with a graceful initials fallback when the image is missing or fails to
+  load. Applies to the table `relation`/`select`/`status`/`badge` cells; the
+  searchable picker (`DynamicSelectField`) and the detail-view picker already
+  rendered option images. Adds a pure `resolveRelationImage` helper (+ tests).
+
 ## 17.0.3
 
 ### Patch Changes

package/dist/dynamic-columns.d.ts

@@ -61,6 +61,14 @@ export declare function formatDateCell(value: unknown, renderAs: string | undefi
  *   - else:     the raw value coerced to string ('' when nullish).
  */
 export declare const resolveRelationLabel: (col: ColumnDefinition, row: any) => string;
+/**
+ * Reads the thumbnail URL a backend serves on a resolved FK sibling, when
+ * present. The backend stamps `image` onto the `{ value, label }` relation
+ * object when the referenced model carries an image column (brand logo,
+ * product photo, customer avatar). Returns '' when there is no sibling image —
+ * the chip then renders text-only, exactly as before.
+ */
+export declare const resolveRelationImage: (col: ColumnDefinition, row: any) => string;
 /**
  * Builds the canonical column factory used by `<DynamicTable>` when the host
  * does not supply its own. Pass `{ getImageUrl, apiBaseUrl }` to wire avatar

package/dist/dynamic-columns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-columns.d.ts","sourceRoot":"","sources":["../src/dynamic-columns.tsx"],"names":[],"mappings":"AAgBA,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,UAAU,CAAA;AAgC9C,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE9D,OAAO,KAAK,EAER,iBAAiB,EACpB,MAAM,wBAAwB,CAAA;AAE/B,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAgGD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OAMlE,CAAA;AA0HD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,KAAG,MAGnE,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,eAAe,2DAA4D,CAAA;AAExF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,GACf;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAY5C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,gBAAgB,EAAE,KAAK,GAAG,KAAG,MAWtE,CAAA;AAiED;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,GAAE,qBAA0B,GACpC,iBAAiB,CAsmBnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBACL,CAAA"}
+{"version":3,"file":"dynamic-columns.d.ts","sourceRoot":"","sources":["../src/dynamic-columns.tsx"],"names":[],"mappings":"AAgBA,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,UAAU,CAAA;AAgC9C,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE9D,OAAO,KAAK,EAER,iBAAiB,EACpB,MAAM,wBAAwB,CAAA;AAE/B,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAgGD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OAMlE,CAAA;AAqKD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,KAAG,MAGnE,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,eAAe,2DAA4D,CAAA;AAExF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,GACf;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAY5C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,gBAAgB,EAAE,KAAK,GAAG,KAAG,MAWtE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,gBAAgB,EAAE,KAAK,GAAG,KAAG,MAOtE,CAAA;AA0ED;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,GAAE,qBAA0B,GACpC,iBAAiB,CAsmBnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBACL,CAAA"}

package/dist/dynamic-columns.js

@@ -169,7 +169,16 @@ const renderRelationBadges = (items, col) => {
             return (_jsxs(Badge, { variant: "outline", className: "flex items-center gap-1", children: [iconValue && (_jsx(DynamicIcon, { name: iconValue, className: "h-3 w-3" })), _jsx("span", { children: label })] }, `${col.key}-${idx}`));
         }) }));
 };
-const OptionBadge = ({ option }) => {
+/**
+ * Tiny square thumbnail for a resolved relation/option that carries an `image`
+ * (brand logo, product photo, customer/user avatar). Uses the same Avatar
+ * primitive as the `avatar`/`creator` cells so a broken/loading image
+ * gracefully falls back to the record's initials. Sized small (the box is an
+ * inline style so an addon-arbitrary Tailwind class never gets dropped by a
+ * consuming app's class scan). Rendered inline alongside a label — never alone.
+ */
+const RelationThumbnail = ({ src, alt, getImageUrl, size = 18 }) => (_jsxs(Avatar, { className: "shrink-0 rounded-sm ring-1 ring-border/40", style: { width: size, height: size }, children: [_jsx(AvatarImage, { src: getImageUrl ? getImageUrl(src) : src, alt: alt, className: "object-cover" }), _jsx(AvatarFallback, { className: "rounded-sm bg-primary/10 text-[8px] font-bold text-primary", children: getInitials(alt) })] }));
+const OptionBadge = ({ option, getImageUrl }) => {
     const isDark = useIsDarkTheme();
     // Explicit backend color wins; otherwise derive a stable, cohesive color
     // from the option's value (fallback label) so "dead" gray badges come
@@ -177,14 +186,14 @@ const OptionBadge = ({ option }) => {
     // tailwind safelist — addon-arbitrary classes aren't in the host scan.
     const colorSource = option.color || optionColor(option.value || option.label);
     const colorStyles = generateBadgeStyles(colorSource, { isDark });
-    return (_jsxs(Badge, { variant: "outline", className: "flex items-center gap-1 border-0", style: colorStyles, children: [option.icon && _jsx(DynamicIcon, { name: option.icon, className: "h-3.5 w-3.5" }), _jsx("span", { children: option.label })] }));
+    return (_jsxs(Badge, { variant: "outline", className: "flex items-center gap-1 border-0", style: colorStyles, children: [option.image ? (_jsx(RelationThumbnail, { src: option.image, alt: option.label, getImageUrl: getImageUrl, size: 16 })) : (option.icon && _jsx(DynamicIcon, { name: option.icon, className: "h-3.5 w-3.5" })), _jsx("span", { children: option.label })] }));
 };
-const BadgeWithEndpointOptions = ({ endpoint, value }) => {
+const BadgeWithEndpointOptions = ({ endpoint, value, getImageUrl }) => {
     const { optionsMap } = React.useContext(OptionsContext);
     const options = optionsMap.get(endpoint) || [];
     const option = options.find((opt) => opt.value === value);
     if (option)
-        return _jsx(OptionBadge, { option: option, fallback: String(value) });
+        return _jsx(OptionBadge, { option: option, fallback: String(value), getImageUrl: getImageUrl });
     // No declared option matched → humanize the raw token as a safety net so a
     // cell never shows `in_progress` verbatim (option.label still wins above).
     return _jsx(Badge, { variant: "outline", children: humanizeToken(value) });
@@ -247,24 +256,42 @@ export const resolveRelationLabel = (col, row) => {
         return '';
     return String(raw);
 };
+/**
+ * Reads the thumbnail URL a backend serves on a resolved FK sibling, when
+ * present. The backend stamps `image` onto the `{ value, label }` relation
+ * object when the referenced model carries an image column (brand logo,
+ * product photo, customer avatar). Returns '' when there is no sibling image —
+ * the chip then renders text-only, exactly as before.
+ */
+export const resolveRelationImage = (col, row) => {
+    const sibling = getNestedValue(row, relationKeyFor(col));
+    if (sibling && typeof sibling === 'object') {
+        const img = sibling.image ?? sibling.avatar ?? sibling.photo;
+        if (img !== undefined && img !== null && img !== '')
+            return String(img);
+    }
+    return '';
+};
 /**
  * Renders a resolved FK relation as a clean, truncated chip. Reads the
- * backend-resolved sibling `{ value, label }` (see `relationKeyFor`) and shows
- * its `label`. Falls back to the raw id when no sibling was resolved, and to an
- * empty marker when there is no value at all. Domain-agnostic: works for every
- * `belongs_to` column (category, supplier, warehouse, …) without per-addon code.
+ * backend-resolved sibling `{ value, label[, image] }` (see `relationKeyFor`)
+ * and shows its `label`, prefixed with a small thumbnail when the sibling
+ * carries an `image`. Falls back to the raw id when no sibling was resolved, and
+ * to an empty marker when there is no value at all. Domain-agnostic: works for
+ * every `belongs_to` column (category, supplier, brand, …) without per-addon code.
  */
-const RelationCell = ({ col, row }) => {
+const RelationCell = ({ col, row, getImageUrl }) => {
     const isDark = useIsDarkTheme();
     const display = resolveRelationLabel(col, row);
     if (!display)
         return _jsx(EmptyCell, {});
+    const image = resolveRelationImage(col, row);
     // Deterministic, SUBTLE color keyed on the resolved label — lighter than
     // enum badges (soft tint, no heavy fill) so category/brand chips read as
     // alive yet stay visually distinct from option/status badges. Inline style
     // (hex-derived) bypasses the host tailwind safelist.
     const chipStyles = relationChipStyles(display, { isDark });
-    return (_jsx("span", { className: "inline-flex max-w-[220px] items-center truncate rounded-md px-2 py-0.5 text-sm font-medium", style: chipStyles, title: display, children: _jsx("span", { className: "truncate", children: display }) }));
+    return (_jsxs("span", { className: "inline-flex max-w-[220px] items-center gap-1.5 rounded-md px-2 py-0.5 text-sm font-medium", style: chipStyles, title: display, children: [image && (_jsx(RelationThumbnail, { src: image, alt: display, getImageUrl: getImageUrl, size: 18 })), _jsx("span", { className: "truncate", children: display })] }));
 };
 /**
  * Generic avatar-style cell: round/rounded photo (or initials fallback) +
@@ -334,7 +361,7 @@ export function makeDefaultGetDynamicColumns(helpers = {}) {
                     if (renderAs === 'badge' && col.useOptions && col.searchEndpoint) {
                         if (!value)
                             return _jsx("span", { className: "text-muted-foreground", children: "-" });
-                        return _jsx(BadgeWithEndpointOptions, { endpoint: col.searchEndpoint, value: value });
+                        return _jsx(BadgeWithEndpointOptions, { endpoint: col.searchEndpoint, value: value, getImageUrl: getImageUrl });
                     }
                     // Static badge options — map value → label/icon/color
                     if (renderAs === 'badge' && col.options && col.options.length > 0) {
@@ -342,7 +369,7 @@ export function makeDefaultGetDynamicColumns(helpers = {}) {
                             return _jsx("span", { className: "text-muted-foreground", children: "-" });
                         const option = col.options.find((o) => o.value === String(value));
                         if (option)
-                            return _jsx(OptionBadge, { option: option, fallback: String(value) });
+                            return _jsx(OptionBadge, { option: option, fallback: String(value), getImageUrl: getImageUrl });
                         return _jsx(Badge, { variant: "outline", children: humanizeToken(value) });
                     }
                     if (renderAs === 'relation-badge-list') {
@@ -362,7 +389,7 @@ export function makeDefaultGetDynamicColumns(helpers = {}) {
                         const sv = String(value);
                         const option = col.options?.find((o) => o.value === sv);
                         if (option)
-                            return _jsx(OptionBadge, { option: option, fallback: sv });
+                            return _jsx(OptionBadge, { option: option, fallback: sv, getImageUrl: getImageUrl });
                         const isDark = typeof document !== 'undefined' &&
                             document.documentElement.classList.contains('dark');
                         const styles = generateBadgeStyles(statusColorFor(sv), { isDark });
@@ -377,7 +404,7 @@ export function makeDefaultGetDynamicColumns(helpers = {}) {
                     // `row[<key w/o _id>] = { value, label }` sibling.
                     if (renderAs === 'relation' ||
                         (col.ref && !col.options?.length && renderAs !== 'badge' && renderAs !== 'status')) {
-                        return _jsx(RelationCell, { col: col, row: row.original });
+                        return _jsx(RelationCell, { col: col, row: row.original, getImageUrl: getImageUrl });
                     }
                     // Option/type column: a `select`-style column ships its
                     // localized `options: [{value,label,color,icon}]` inline and
@@ -391,7 +418,7 @@ export function makeDefaultGetDynamicColumns(helpers = {}) {
                             return _jsx(EmptyCell, {});
                         const option = col.options.find((o) => o.value === String(value));
                         if (option)
-                            return _jsx(OptionBadge, { option: option, fallback: String(value) });
+                            return _jsx(OptionBadge, { option: option, fallback: String(value), getImageUrl: getImageUrl });
                         return _jsx(Badge, { variant: "outline", children: humanizeToken(value) });
                     }
                     switch (renderAs) {

package/dist/dynamic-select-field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-select-field.d.ts","sourceRoot":"","sources":["../src/dynamic-select-field.tsx"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAgD7C,MAAM,WAAW,uBAAuB;IACpC,KAAK,EAAE,cAAc,CAAA;IACrB,KAAK,EAAE,GAAG,CAAA;IACV,QAAQ,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,CAAA;CAC7B;AAED,wBAAgB,kBAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,uBAAuB,+BA2KrF;AAED,eAAe,kBAAkB,CAAA"}
+{"version":3,"file":"dynamic-select-field.d.ts","sourceRoot":"","sources":["../src/dynamic-select-field.tsx"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AA+F7C,MAAM,WAAW,uBAAuB;IACpC,KAAK,EAAE,cAAc,CAAA;IACrB,KAAK,EAAE,GAAG,CAAA;IACV,QAAQ,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,CAAA;CAC7B;AAED,wBAAgB,kBAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,uBAAuB,+BA0KrF;AAED,eAAe,kBAAkB,CAAA"}

package/dist/dynamic-select-field.js

@@ -25,6 +25,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import { Button, Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, Popover, PopoverContent, PopoverTrigger, } from '@asteby/metacore-ui/primitives';
 import { Check, ChevronsUpDown, ImageIcon, Loader2, Plus } from 'lucide-react';
+import { resolveColorCss } from '@asteby/metacore-ui/lib';
+import { DynamicIcon } from './dynamic-icon';
 import { useOptionsResolver } from './use-options-resolver';
 import { getFieldRef } from './dynamic-form-schema';
 /**
@@ -46,6 +48,29 @@ function OptionThumb({ image, size = 20 }) {
             e.currentTarget.style.visibility = 'hidden';
         } }));
 }
+/**
+ * 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.
+ */
+function OptionLead({ option, size = 20, }) {
+    if (!option)
+        return null;
+    if (option.image)
+        return _jsx(OptionThumb, { image: option.image, 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 }));
+    }
+    return null;
+}
+/** True when any option (or the selected one) carries a renderable visual. */
+function optionsHaveVisual(options, selected) {
+    const has = (o) => !!(o && (o.image || o.color || o.icon));
+    return has(selected) || options.some(has);
+}
 function useDebounced(value, ms) {
     const [debounced, setDebounced] = useState(value);
     useEffect(() => {
@@ -87,7 +112,7 @@ export function DynamicSelectField({ field, value, onChange }) {
     // Only switch the picker into "with thumbnails" mode when the data actually
     // carries images — a relation whose options have no `image` keeps the plain
     // text list it had before (no empty placeholder column).
-    const hasImages = !!selectedOption?.image || options.some((o) => !!o.image);
+    const hasVisual = optionsHaveVisual(options, selectedOption);
     const handlePick = (opt) => {
         setPicked(opt);
         onChange(String(opt.id));
@@ -119,12 +144,12 @@ export function DynamicSelectField({ field, value, onChange }) {
     // to the cell. Without min-w-0 the combobox+button row sizes to its content
     // (the long empty-state placeholder) and overflows the column, pushing the
     // "+" off-screen — it only "fit" once a short value was selected.
-    return (_jsxs("div", { className: "flex w-full min-w-0 items-center gap-1.5", children: [_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { type: "button", variant: "outline", role: "combobox", "aria-expanded": open, id: field.key, className: "min-w-0 flex-1 justify-between font-normal", "data-empty": !value, children: [_jsxs("span", { className: "flex min-w-0 flex-1 items-center gap-2 text-left", children: [hasImages && value ? (_jsx(OptionThumb, { image: selectedOption?.image, size: 20 })) : null, _jsx("span", { className: 'min-w-0 flex-1 truncate ' + (selectedLabel ? '' : 'text-muted-foreground'), children: selectedLabel || field.placeholder || 'Buscar…' })] }), _jsx(ChevronsUpDown, { className: "ml-2 size-4 shrink-0 opacity-50" })] }) }), _jsx(PopoverContent, { className: "p-0", align: "start", 
+    return (_jsxs("div", { className: "flex w-full min-w-0 items-center gap-1.5", children: [_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { type: "button", variant: "outline", role: "combobox", "aria-expanded": open, id: field.key, className: "min-w-0 flex-1 justify-between font-normal", "data-empty": !value, children: [_jsxs("span", { className: "flex min-w-0 flex-1 items-center gap-2 text-left", children: [hasVisual && value ? (_jsx(OptionLead, { option: selectedOption, size: 20 })) : null, _jsx("span", { className: 'min-w-0 flex-1 truncate ' + (selectedLabel ? '' : 'text-muted-foreground'), children: selectedLabel || field.placeholder || 'Buscar…' })] }), _jsx(ChevronsUpDown, { className: "ml-2 size-4 shrink-0 opacity-50" })] }) }), _jsx(PopoverContent, { className: "p-0", align: "start", 
                         // Match the trigger width without an arbitrary Tailwind class
                         // (those don't always survive a consuming app's Tailwind scan).
                         style: { width: 'var(--radix-popover-trigger-width)' }, children: _jsxs(Command, { shouldFilter: false, children: [_jsx(CommandInput, { placeholder: field.placeholder || 'Buscar…', value: search, onValueChange: setSearch }), _jsxs(CommandList, { children: [loading && (_jsxs("div", { className: "text-muted-foreground flex items-center justify-center gap-2 py-6 text-sm", children: [_jsx(Loader2, { className: "size-4 animate-spin" }), "Buscando\u2026"] })), !loading && options.length === 0 && (_jsx(CommandEmpty, { children: debounced ? 'Sin resultados' : 'Escribí para buscar…' })), !loading && options.length > 0 && (_jsx(CommandGroup, { className: "max-h-64 overflow-auto", children: options.map((opt) => {
                                                 const isSel = String(opt.id) === String(value);
-                                                return (_jsxs(CommandItem, { value: String(opt.id), onSelect: () => handlePick(opt), children: [_jsx(Check, { className: 'mr-2 size-4 shrink-0 ' + (isSel ? 'opacity-100' : 'opacity-0') }), hasImages && (_jsx(OptionThumb, { image: opt.image, size: 24 })), _jsxs("div", { className: "ml-2 flex min-w-0 flex-col", children: [_jsx("span", { className: "truncate", children: opt.label }), opt.description && (_jsx("span", { className: "text-muted-foreground truncate text-xs", children: opt.description }))] })] }, String(opt.id)));
+                                                return (_jsxs(CommandItem, { value: String(opt.id), onSelect: () => handlePick(opt), children: [_jsx(Check, { className: 'mr-2 size-4 shrink-0 ' + (isSel ? 'opacity-100' : 'opacity-0') }), hasVisual && (_jsx(OptionLead, { option: opt, size: 24 })), _jsxs("div", { className: "ml-2 flex min-w-0 flex-col", children: [_jsx("span", { className: "truncate", children: opt.label }), opt.description && (_jsx("span", { className: "text-muted-foreground truncate text-xs", children: opt.description }))] })] }, String(opt.id)));
                                             }) }))] })] }) })] }), fieldRef && (_jsx(Button, { type: "button", variant: "outline", size: "icon", className: "size-9 shrink-0", onClick: openCreate, title: `Crear ${field.label ?? fieldRef}`, "aria-label": `Crear ${field.label ?? fieldRef}`, children: _jsx(Plus, { className: "size-4" }) }))] }));
 }
 export default DynamicSelectField;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "17.0.3",
+  "version": "18.0.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "date-fns": ">=3",
     "react-day-picker": ">=8",
     "@asteby/metacore-sdk": "^3.2.0",
-    "@asteby/metacore-ui": "^2.4.2"
+    "@asteby/metacore-ui": "^2.5.0"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-router": {
@@ -62,7 +62,7 @@
     "vitest": "^4.0.0",
     "zustand": "^5.0.0",
     "@asteby/metacore-sdk": "3.2.0",
-    "@asteby/metacore-ui": "2.4.2"
+    "@asteby/metacore-ui": "2.5.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/__tests__/relation-option-cells.test.ts

@@ -3,7 +3,7 @@
 // host's render tests); here we lock the value-resolution contract that drives
 // them so a backend shape change is caught without a DOM.
 import { describe, it, expect } from 'vitest'
-import { relationKeyFor, resolveRelationLabel } from '../dynamic-columns'
+import { relationKeyFor, resolveRelationImage, resolveRelationLabel } from '../dynamic-columns'
 import type { ColumnDefinition } from '../types'
 
 const col = (over: Partial<ColumnDefinition>): ColumnDefinition => ({
@@ -64,3 +64,44 @@ describe('resolveRelationLabel', () => {
         expect(resolveRelationLabel(col({ ref: 'categories' }), row)).toBe('Sin categoría')
     })
 })
+
+describe('resolveRelationImage', () => {
+    const brandCol = (over: Partial<ColumnDefinition> = {}): ColumnDefinition =>
+        col({ key: 'brand_id', label: 'Marca', ref: 'brands', ...over })
+
+    it('reads the thumbnail the backend stamps on the resolved sibling', () => {
+        const row = {
+            brand_id: 'uuid-1',
+            brand: { value: 'uuid-1', label: 'Michelin', image: 'https://cdn/x/m.png' },
+        }
+        expect(resolveRelationImage(brandCol(), row)).toBe('https://cdn/x/m.png')
+    })
+
+    it('also accepts avatar/photo aliases on the sibling', () => {
+        expect(
+            resolveRelationImage(brandCol(), {
+                brand: { value: 'u', label: 'X', avatar: 'a.png' },
+            }),
+        ).toBe('a.png')
+        expect(
+            resolveRelationImage(brandCol(), {
+                brand: { value: 'u', label: 'X', photo: 'p.png' },
+            }),
+        ).toBe('p.png')
+    })
+
+    it('returns empty string when the sibling carries no image (text-only chip)', () => {
+        const row = { brand_id: 'uuid-2', brand: { value: 'uuid-2', label: 'Genérica' } }
+        expect(resolveRelationImage(brandCol(), row)).toBe('')
+    })
+
+    it('returns empty string when there is no sibling at all', () => {
+        expect(resolveRelationImage(brandCol(), { brand_id: 'uuid-3' })).toBe('')
+        expect(resolveRelationImage(brandCol(), {})).toBe('')
+    })
+
+    it('ignores an empty-string image (no broken thumbnail)', () => {
+        const row = { brand: { value: 'u', label: 'X', image: '' } }
+        expect(resolveRelationImage(brandCol(), row)).toBe('')
+    })
+})

package/src/dynamic-columns.tsx

@@ -272,12 +272,42 @@ const renderRelationBadges = (items: any, col: ColumnDefinition) => {
     )
 }
 
+/**
+ * Tiny square thumbnail for a resolved relation/option that carries an `image`
+ * (brand logo, product photo, customer/user avatar). Uses the same Avatar
+ * primitive as the `avatar`/`creator` cells so a broken/loading image
+ * gracefully falls back to the record's initials. Sized small (the box is an
+ * inline style so an addon-arbitrary Tailwind class never gets dropped by a
+ * consuming app's class scan). Rendered inline alongside a label — never alone.
+ */
+const RelationThumbnail: React.FC<{
+    src: string
+    alt: string
+    getImageUrl?: (path: string) => string
+    size?: number
+}> = ({ src, alt, getImageUrl, size = 18 }) => (
+    <Avatar
+        className="shrink-0 rounded-sm ring-1 ring-border/40"
+        style={{ width: size, height: size }}
+    >
+        <AvatarImage
+            src={getImageUrl ? getImageUrl(src) : src}
+            alt={alt}
+            className="object-cover"
+        />
+        <AvatarFallback className="rounded-sm bg-primary/10 text-[8px] font-bold text-primary">
+            {getInitials(alt)}
+        </AvatarFallback>
+    </Avatar>
+)
+
 interface OptionBadgeProps {
-    option: { value: string; label: string; icon?: string; color?: string }
+    option: { value: string; label: string; icon?: string; color?: string; image?: string }
     fallback: string
+    getImageUrl?: (path: string) => string
 }
 
-const OptionBadge: React.FC<OptionBadgeProps> = ({ option }) => {
+const OptionBadge: React.FC<OptionBadgeProps> = ({ option, getImageUrl }) => {
     const isDark = useIsDarkTheme()
     // Explicit backend color wins; otherwise derive a stable, cohesive color
     // from the option's value (fallback label) so "dead" gray badges come
@@ -287,17 +317,30 @@ const OptionBadge: React.FC<OptionBadgeProps> = ({ option }) => {
     const colorStyles = generateBadgeStyles(colorSource, { isDark })
     return (
         <Badge variant="outline" className="flex items-center gap-1 border-0" style={colorStyles}>
-            {option.icon && <DynamicIcon name={option.icon} className="h-3.5 w-3.5" />}
+            {option.image ? (
+                <RelationThumbnail
+                    src={option.image}
+                    alt={option.label}
+                    getImageUrl={getImageUrl}
+                    size={16}
+                />
+            ) : (
+                option.icon && <DynamicIcon name={option.icon} className="h-3.5 w-3.5" />
+            )}
             <span>{option.label}</span>
         </Badge>
     )
 }
 
-const BadgeWithEndpointOptions: React.FC<{ endpoint: string; value: any }> = ({ endpoint, value }) => {
+const BadgeWithEndpointOptions: React.FC<{
+    endpoint: string
+    value: any
+    getImageUrl?: (path: string) => string
+}> = ({ endpoint, value, getImageUrl }) => {
     const { optionsMap } = React.useContext(OptionsContext)
     const options = optionsMap.get(endpoint) || []
     const option = options.find((opt: any) => opt.value === value)
-    if (option) return <OptionBadge option={option} fallback={String(value)} />
+    if (option) return <OptionBadge option={option} fallback={String(value)} getImageUrl={getImageUrl} />
     // No declared option matched → humanize the raw token as a safety net so a
     // cell never shows `in_progress` verbatim (option.label still wins above).
     return <Badge variant="outline">{humanizeToken(value)}</Badge>
@@ -366,17 +409,39 @@ export const resolveRelationLabel = (col: ColumnDefinition, row: any): string =>
     return String(raw)
 }
 
+/**
+ * Reads the thumbnail URL a backend serves on a resolved FK sibling, when
+ * present. The backend stamps `image` onto the `{ value, label }` relation
+ * object when the referenced model carries an image column (brand logo,
+ * product photo, customer avatar). Returns '' when there is no sibling image —
+ * the chip then renders text-only, exactly as before.
+ */
+export const resolveRelationImage = (col: ColumnDefinition, row: any): string => {
+    const sibling = getNestedValue(row, relationKeyFor(col))
+    if (sibling && typeof sibling === 'object') {
+        const img = sibling.image ?? sibling.avatar ?? sibling.photo
+        if (img !== undefined && img !== null && img !== '') return String(img)
+    }
+    return ''
+}
+
 /**
  * Renders a resolved FK relation as a clean, truncated chip. Reads the
- * backend-resolved sibling `{ value, label }` (see `relationKeyFor`) and shows
- * its `label`. Falls back to the raw id when no sibling was resolved, and to an
- * empty marker when there is no value at all. Domain-agnostic: works for every
- * `belongs_to` column (category, supplier, warehouse, …) without per-addon code.
+ * backend-resolved sibling `{ value, label[, image] }` (see `relationKeyFor`)
+ * and shows its `label`, prefixed with a small thumbnail when the sibling
+ * carries an `image`. Falls back to the raw id when no sibling was resolved, and
+ * to an empty marker when there is no value at all. Domain-agnostic: works for
+ * every `belongs_to` column (category, supplier, brand, …) without per-addon code.
  */
-const RelationCell: React.FC<{ col: ColumnDefinition; row: any }> = ({ col, row }) => {
+const RelationCell: React.FC<{
+    col: ColumnDefinition
+    row: any
+    getImageUrl?: (path: string) => string
+}> = ({ col, row, getImageUrl }) => {
     const isDark = useIsDarkTheme()
     const display = resolveRelationLabel(col, row)
     if (!display) return <EmptyCell />
+    const image = resolveRelationImage(col, row)
     // Deterministic, SUBTLE color keyed on the resolved label — lighter than
     // enum badges (soft tint, no heavy fill) so category/brand chips read as
     // alive yet stay visually distinct from option/status badges. Inline style
@@ -384,10 +449,13 @@ const RelationCell: React.FC<{ col: ColumnDefinition; row: any }> = ({ col, row
     const chipStyles = relationChipStyles(display, { isDark })
     return (
         <span
-            className="inline-flex max-w-[220px] items-center truncate rounded-md px-2 py-0.5 text-sm font-medium"
+            className="inline-flex max-w-[220px] items-center gap-1.5 rounded-md px-2 py-0.5 text-sm font-medium"
             style={chipStyles}
             title={display}
         >
+            {image && (
+                <RelationThumbnail src={image} alt={display} getImageUrl={getImageUrl} size={18} />
+            )}
             <span className="truncate">{display}</span>
         </span>
     )
@@ -523,14 +591,14 @@ export function makeDefaultGetDynamicColumns(
                     // Endpoint-loaded badge options (preloaded into OptionsContext)
                     if (renderAs === 'badge' && col.useOptions && col.searchEndpoint) {
                         if (!value) return <span className="text-muted-foreground">-</span>
-                        return <BadgeWithEndpointOptions endpoint={col.searchEndpoint} value={value} />
+                        return <BadgeWithEndpointOptions endpoint={col.searchEndpoint} value={value} getImageUrl={getImageUrl} />
                     }
 
                     // Static badge options — map value → label/icon/color
                     if (renderAs === 'badge' && col.options && col.options.length > 0) {
                         if (!value && value !== 0) return <span className="text-muted-foreground">-</span>
                         const option = col.options.find((o) => o.value === String(value))
-                        if (option) return <OptionBadge option={option} fallback={String(value)} />
+                        if (option) return <OptionBadge option={option} fallback={String(value)} getImageUrl={getImageUrl} />
                         return <Badge variant="outline">{humanizeToken(value)}</Badge>
                     }
 
@@ -550,7 +618,7 @@ export function makeDefaultGetDynamicColumns(
                         if (!value && value !== 0) return <EmptyCell />
                         const sv = String(value)
                         const option = col.options?.find((o) => o.value === sv)
-                        if (option) return <OptionBadge option={option} fallback={sv} />
+                        if (option) return <OptionBadge option={option} fallback={sv} getImageUrl={getImageUrl} />
                         const isDark =
                             typeof document !== 'undefined' &&
                             document.documentElement.classList.contains('dark')
@@ -573,7 +641,7 @@ export function makeDefaultGetDynamicColumns(
                         renderAs === 'relation' ||
                         (col.ref && !col.options?.length && renderAs !== 'badge' && renderAs !== 'status')
                     ) {
-                        return <RelationCell col={col} row={row.original} />
+                        return <RelationCell col={col} row={row.original} getImageUrl={getImageUrl} />
                     }
 
                     // Option/type column: a `select`-style column ships its
@@ -588,7 +656,7 @@ export function makeDefaultGetDynamicColumns(
                     ) {
                         if (!value && value !== 0) return <EmptyCell />
                         const option = col.options.find((o) => o.value === String(value))
-                        if (option) return <OptionBadge option={option} fallback={String(value)} />
+                        if (option) return <OptionBadge option={option} fallback={String(value)} getImageUrl={getImageUrl} />
                         return <Badge variant="outline">{humanizeToken(value)}</Badge>
                     }
 

package/src/dynamic-select-field.tsx

@@ -35,6 +35,8 @@ import {
     PopoverTrigger,
 } from '@asteby/metacore-ui/primitives'
 import { Check, ChevronsUpDown, ImageIcon, Loader2, Plus } from 'lucide-react'
+import { resolveColorCss } from '@asteby/metacore-ui/lib'
+import { DynamicIcon } from './dynamic-icon'
 import { useOptionsResolver, type ResolvedOption } from './use-options-resolver'
 import { getFieldRef } from './dynamic-form-schema'
 import type { ActionFieldDef } from './types'
@@ -76,6 +78,53 @@ function OptionThumb({ image, size = 20 }: { image?: string | null; size?: numbe
     )
 }
 
+/**
+ * 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.
+ */
+function OptionLead({
+    option,
+    size = 20,
+}: {
+    option?: Pick<ResolvedOption, 'image' | 'color' | 'icon'> | null
+    size?: number
+}) {
+    if (!option) return null
+    if (option.image) return <OptionThumb image={option.image} 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
+            />
+        )
+    }
+    return null
+}
+
+/** True when any option (or the selected one) carries a renderable visual. */
+function optionsHaveVisual(
+    options: ReadonlyArray<Pick<ResolvedOption, 'image' | 'color' | 'icon'>>,
+    selected?: Pick<ResolvedOption, 'image' | 'color' | 'icon'> | null,
+): boolean {
+    const has = (o?: Pick<ResolvedOption, 'image' | 'color' | 'icon'> | null) =>
+        !!(o && (o.image || o.color || o.icon))
+    return has(selected) || options.some(has)
+}
+
 function useDebounced<T>(value: T, ms: number): T {
     const [debounced, setDebounced] = useState(value)
     useEffect(() => {
@@ -130,8 +179,7 @@ export function DynamicSelectField({ field, value, onChange }: DynamicSelectFiel
     // Only switch the picker into "with thumbnails" mode when the data actually
     // carries images — a relation whose options have no `image` keeps the plain
     // text list it had before (no empty placeholder column).
-    const hasImages =
-        !!selectedOption?.image || options.some((o) => !!o.image)
+    const hasVisual = optionsHaveVisual(options, selectedOption)
 
     const handlePick = (opt: ResolvedOption) => {
         setPicked(opt)
@@ -181,8 +229,8 @@ export function DynamicSelectField({ field, value, onChange }: DynamicSelectFiel
                     data-empty={!value}
                 >
                     <span className="flex min-w-0 flex-1 items-center gap-2 text-left">
-                        {hasImages && value ? (
-                            <OptionThumb image={selectedOption?.image} size={20} />
+                        {hasVisual && value ? (
+                            <OptionLead option={selectedOption} size={20} />
                         ) : null}
                         <span className={'min-w-0 flex-1 truncate ' + (selectedLabel ? '' : 'text-muted-foreground')}>
                             {selectedLabel || field.placeholder || 'Buscar…'}
@@ -227,8 +275,8 @@ export function DynamicSelectField({ field, value, onChange }: DynamicSelectFiel
                                             onSelect={() => handlePick(opt)}
                                         >
                                             <Check className={'mr-2 size-4 shrink-0 ' + (isSel ? 'opacity-100' : 'opacity-0')} />
-                                            {hasImages && (
-                                                <OptionThumb image={opt.image} size={24} />
+                                            {hasVisual && (
+                                                <OptionLead option={opt} size={24} />
                                             )}
                                             <div className="ml-2 flex min-w-0 flex-col">
                                                 <span className="truncate">{opt.label}</span>