@asteby/metacore-runtime-react 24.0.1 → 24.0.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @asteby/metacore-runtime-react
 
+## 24.0.2
+
+### Patch Changes
+
+- a27d1a2: feat(relations): secondary identifier (SKU/email) under a reference chip
+
+  Reference chips (resolved FK cells, endpoint-option badges, jsonb line-item refs,
+  confirm-modal items) now render a muted secondary line under the label — a
+  product's SKU, a user's email — so a resolved record reads "Name / SKU" instead
+  of a bare name. Declarative: the SDK reads the backend-projected `subtitle` /
+  `description` on the option or resolved sibling (never a hardcoded column). Absent
+  → single-line as before. The select picker already surfaced `description`; this
+  brings the resolved-chip surfaces in line.
+
 ## 24.0.1
 
 ### Patch Changes

package/dist/collection-cell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection-cell.d.ts","sourceRoot":"","sources":["../src/collection-cell.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAkD9B,sFAAsF;AACtF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,KAAK,MAAM,CAAA;AAE9D;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACtB,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAA;IACX,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAA;IACb,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAA;CACf;AAoND;;;;;;GAMG;AACH,wBAAgB,WAAW,CACvB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,EACf,CAAC,CAAC,EAAE,SAAS,GACd,MAAM,CAWR;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACtB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,EACf,CAAC,CAAC,EAAE,SAAS,GACd,MAAM,CAcR;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYnD;AAiOD,MAAM,WAAW,mBAAmB;IAChC,KAAK,EAAE,OAAO,CAAA;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,CAAC,CAAC,EAAE,SAAS,CAAA;IACb;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,SAAS,EAAE,CAAA;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAA;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAC3B,KAAK,EACL,SAAa,EACb,MAAM,EACN,CAAC,EACD,UAAU,EACV,WAAW,EACX,OAAiB,GACpB,EAAE,mBAAmB,qBA2HrB"}
+{"version":3,"file":"collection-cell.d.ts","sourceRoot":"","sources":["../src/collection-cell.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAkD9B,sFAAsF;AACtF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,KAAK,MAAM,CAAA;AAE9D;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACtB,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAA;IACX,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAA;IACb,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAA;CACf;AAwOD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACvB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,EACf,CAAC,CAAC,EAAE,SAAS,GACd,MAAM,CAWR;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACtB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,EACf,CAAC,CAAC,EAAE,SAAS,GACd,MAAM,CAcR;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYnD;AAkOD,MAAM,WAAW,mBAAmB;IAChC,KAAK,EAAE,OAAO,CAAA;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,CAAC,CAAC,EAAE,SAAS,CAAA;IACb;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,SAAS,EAAE,CAAA;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAA;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAC3B,KAAK,EACL,SAAa,EACb,MAAM,EACN,CAAC,EACD,UAAU,EACV,WAAW,EACX,OAAiB,GACpB,EAAE,mBAAmB,qBA2HrB"}

package/dist/collection-cell.js

@@ -55,12 +55,16 @@ function resolvedRefFor(field, row) {
         const obj = sibling;
         const label = obj.label;
         if (label !== undefined && label !== null && label !== '') {
+            const sub = obj.subtitle ?? obj.description;
             return {
                 label: String(label),
                 value: obj.value,
                 image: typeof obj.image === 'string' && obj.image !== ''
                     ? obj.image
                     : undefined,
+                subtitle: sub !== undefined && sub !== null && sub !== ''
+                    ? String(sub)
+                    : undefined,
             };
         }
     }
@@ -92,10 +96,12 @@ function resolvedRefObject(v) {
     const label = v.label;
     if (label === undefined || label === null || label === '')
         return null;
+    const sub = v.subtitle ?? v.description;
     return {
         label: String(label),
         value: v.value,
         image: typeof v.image === 'string' && v.image !== '' ? v.image : undefined,
+        subtitle: sub !== undefined && sub !== null && sub !== '' ? String(sub) : undefined,
     };
 }
 /**
@@ -104,9 +110,10 @@ function resolvedRefObject(v) {
  * resolved name. The exact look the FK table columns use, so resolved relations
  * read consistently everywhere (table popover, detail view, edit, line items).
  */
-function RefChip({ label, image, getImageUrl, }) {
+function RefChip({ label, image, subtitle, getImageUrl, }) {
     const isDark = useIsDarkTheme();
-    return (_jsxs("span", { className: "inline-flex max-w-[220px] items-center gap-1.5 rounded-md px-2 py-0.5 text-xs font-medium", style: relationChipStyles(label, { isDark }), title: label, children: [image ? (_jsxs(Avatar, { className: "shrink-0 rounded-sm ring-1 ring-border/40", style: { width: 18, height: 18 }, children: [_jsx(AvatarImage, { src: getImageUrl ? getImageUrl(image) : image, alt: label, className: "object-cover" }), _jsx(AvatarFallback, { className: "rounded-sm bg-primary/10 text-[8px] font-bold text-primary", children: getInitials(label) })] })) : (_jsx(Box, { className: "h-3 w-3 shrink-0 opacity-70" })), _jsx("span", { className: "truncate", children: label })] }));
+    const size = subtitle ? 24 : 18;
+    return (_jsxs("span", { className: "inline-flex max-w-[220px] items-center gap-1.5 rounded-md px-2 py-0.5 text-xs font-medium", style: relationChipStyles(label, { isDark }), title: subtitle ? `${label} · ${subtitle}` : label, children: [image ? (_jsxs(Avatar, { className: "shrink-0 rounded-sm ring-1 ring-border/40", style: { width: size, height: size }, children: [_jsx(AvatarImage, { src: getImageUrl ? getImageUrl(image) : image, alt: label, className: "object-cover" }), _jsx(AvatarFallback, { className: "rounded-sm bg-primary/10 text-[8px] font-bold text-primary", children: getInitials(label) })] })) : (_jsx(Box, { className: "h-3 w-3 shrink-0 opacity-70" })), subtitle ? (_jsxs("span", { className: "flex flex-col leading-tight min-w-0", children: [_jsx("span", { className: "truncate", children: label }), _jsx("span", { className: "truncate text-[0.65rem] opacity-70", children: subtitle })] })) : (_jsx("span", { className: "truncate", children: label }))] }));
 }
 /**
  * Visual cell for one declared item-field. A resolved `ref` renders as a
@@ -117,7 +124,7 @@ function RefChip({ label, image, getImageUrl, }) {
 function ItemFieldCell({ field, row, getImageUrl, }) {
     const ref = resolvedRefFor(field, row);
     if (ref?.label) {
-        return (_jsx(RefChip, { label: ref.label, image: ref.image, getImageUrl: getImageUrl }));
+        return (_jsx(RefChip, { label: ref.label, image: ref.image, subtitle: ref.subtitle, getImageUrl: getImageUrl }));
     }
     return _jsx(_Fragment, { children: formatScalar(row[field.key]) });
 }
@@ -311,7 +318,7 @@ function MiniTable({ rows, locale, t, itemFields, getImageUrl, }) {
                         const ref = refKeys.has(key)
                             ? resolvedRefObject(row[key])
                             : null;
-                        return (_jsx(TableCell, { className: "text-xs whitespace-nowrap", children: ref ? (_jsx(RefChip, { label: ref.label, image: ref.image, getImageUrl: getImageUrl })) : (formatScalar(row[key])) }, key));
+                        return (_jsx(TableCell, { className: "text-xs whitespace-nowrap", children: ref ? (_jsx(RefChip, { label: ref.label, image: ref.image, subtitle: ref.subtitle, getImageUrl: getImageUrl })) : (formatScalar(row[key])) }, key));
                     }) }, i))) })] }));
 }
 function ScalarList({ values }) {

package/dist/display-value.d.ts

@@ -39,6 +39,15 @@ export interface DisplayOption {
     icon?: string;
     color?: string;
     image?: string;
+    /**
+     * Secondary identifier shown UNDER the label (muted, smaller) — a product's
+     * SKU/barcode, a user's email, etc. Lets a reference chip read like
+     * "Camiseta / SKU-001" instead of a bare name, so a resolved record is
+     * unambiguous. Populated declaratively: the backend projects it as the
+     * option/relation `description` (SearchConfig/FieldOptionsConfig.Description,
+     * or a column's `label_description`). Absent → single-line label as before.
+     */
+    subtitle?: string;
 }
 /**
  * Colored option badge — the canonical "pro" pill for a select/status/badge

package/dist/display-value.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"display-value.d.ts","sourceRoot":"","sources":["../src/display-value.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AASzB;;;GAGG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAmBxC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAepD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB,CAcA,CAAA;AAED,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC;IAC/B,MAAM,EAAE,aAAa,CAAA;IACrB,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB,CAmBA,CAAA"}
+{"version":3,"file":"display-value.d.ts","sourceRoot":"","sources":["../src/display-value.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AASzB;;;GAGG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAmBxC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAepD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB,CAcA,CAAA;AAED,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC;IAC/B,MAAM,EAAE,aAAa,CAAA;IACrB,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB,CA8BA,CAAA"}

package/dist/display-value.js

@@ -70,5 +70,5 @@ export const OptionBadge = ({ option, getImageUrl }) => {
     const isDark = useIsDarkTheme();
     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.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 })] }));
+    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: option.subtitle ? 22 : 16 })) : (option.icon && _jsx(DynamicIcon, { name: option.icon, className: "h-3.5 w-3.5" })), option.subtitle ? (_jsxs("span", { className: "flex flex-col leading-tight text-start", children: [_jsx("span", { children: option.label }), _jsx("span", { className: "text-[0.7rem] opacity-70", children: option.subtitle })] })) : (_jsx("span", { children: option.label }))] }));
 };

package/dist/dynamic-columns.d.ts

@@ -112,6 +112,15 @@ export declare const resolveRelationLabel: (col: ColumnDefinition, row: any) =>
  * the chip then renders text-only, exactly as before.
  */
 export declare const resolveRelationImage: (col: ColumnDefinition, row: any) => string;
+/**
+ * Reads a secondary identifier the backend stamps on a resolved FK sibling — a
+ * product's SKU, a user's email — projected as `subtitle`/`description` (the
+ * relational twin of `image` via the column's `label_description`). Rendered
+ * muted under the label so a reference chip reads "Name / SKU". Domain-agnostic:
+ * only the generic `subtitle`/`description` keys are read (never a hardcoded
+ * `sku`/`code`), so the author picks the column declaratively. '' when absent.
+ */
+export declare const resolveRelationSubtitle: (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;AAuC9C,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;AA0BD;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,gBAAgB,EAAE,cAAc,MAAM,KAAG,MACzB,CAAA;AAQrD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,gBAAgB,KAAG,MAAM,GAAG,SAG5D,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC7B,KAAK,gBAAgB,EACrB,OAAO,OAAO,EACd,WAAW,MAAM,EACjB,SAAS,MAAM,KAChB,MAyBF,CAAA;AAyCD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OAMlE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OAiB5D,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OACqB,CAAA;AAqFhF;;;;;;;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;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAClB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA6C5C;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;AAsID;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,GAAE,qBAA0B,GACpC,iBAAiB,CAqmBnB;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;AAuC9C,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;AA0BD;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,gBAAgB,EAAE,cAAc,MAAM,KAAG,MACzB,CAAA;AAQrD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,gBAAgB,KAAG,MAAM,GAAG,SAG5D,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC7B,KAAK,gBAAgB,EACrB,OAAO,OAAO,EACd,WAAW,MAAM,EACjB,SAAS,MAAM,KAChB,MAyBF,CAAA;AAyCD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OAMlE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OAiB5D,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,EAAE,KAAK,GAAG,KAAG,OACqB,CAAA;AAwFhF;;;;;;;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;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAClB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA6C5C;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;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAAI,KAAK,gBAAgB,EAAE,KAAK,GAAG,KAAG,MAOzE,CAAA;AA8ID;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,OAAO,GAAE,qBAA0B,GACpC,iBAAiB,CAqmBnB;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBACL,CAAA"}

package/dist/dynamic-columns.js

@@ -213,8 +213,11 @@ const BadgeWithEndpointOptions = ({ endpoint, value, getImageUrl }) => {
     const { optionsMap } = React.useContext(OptionsContext);
     const options = optionsMap.get(endpoint) || [];
     const option = options.find((opt) => opt.value === value);
+    // Reference options carry the backend-projected `description` (the SKU/email
+    // the author pointed the options config at) — surface it as the chip subtitle
+    // so a resolved record reads "Name / SKU" instead of a bare name.
     if (option)
-        return _jsx(OptionBadge, { option: option, fallback: String(value), getImageUrl: getImageUrl });
+        return _jsx(OptionBadge, { option: { ...option, subtitle: option.subtitle ?? option.description }, 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) });
@@ -336,6 +339,23 @@ export const resolveRelationImage = (col, row) => {
     }
     return '';
 };
+/**
+ * Reads a secondary identifier the backend stamps on a resolved FK sibling — a
+ * product's SKU, a user's email — projected as `subtitle`/`description` (the
+ * relational twin of `image` via the column's `label_description`). Rendered
+ * muted under the label so a reference chip reads "Name / SKU". Domain-agnostic:
+ * only the generic `subtitle`/`description` keys are read (never a hardcoded
+ * `sku`/`code`), so the author picks the column declaratively. '' when absent.
+ */
+export const resolveRelationSubtitle = (col, row) => {
+    const sibling = getNestedValue(row, relationKeyFor(col));
+    if (sibling && typeof sibling === 'object') {
+        const sub = sibling.subtitle ?? sibling.description;
+        if (sub !== undefined && sub !== null && sub !== '')
+            return String(sub);
+    }
+    return '';
+};
 /**
  * Renders a resolved FK relation as a clean, truncated chip. Reads the
  * backend-resolved sibling `{ value, label[, image] }` (see `relationKeyFor`)
@@ -350,12 +370,13 @@ const RelationCell = ({ col, row, getImageUrl }) => {
     if (!display)
         return _jsx(EmptyCell, {});
     const image = resolveRelationImage(col, row);
+    const subtitle = resolveRelationSubtitle(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 (_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 })] }));
+    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: subtitle ? `${display} · ${subtitle}` : display, children: [image && (_jsx(RelationThumbnail, { src: image, alt: display, getImageUrl: getImageUrl, size: subtitle ? 24 : 18 })), subtitle ? (_jsxs("span", { className: "flex flex-col leading-tight min-w-0", children: [_jsx("span", { className: "truncate", children: display }), _jsx("span", { className: "truncate text-[0.7rem] opacity-70", children: subtitle })] })) : (_jsx("span", { className: "truncate", children: display }))] }));
 };
 /**
  * Renders a SAP-style polymorphic source-document reference as a navigable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "24.0.1",
+  "version": "24.0.2",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",
@@ -37,8 +37,8 @@
     "react-i18next": ">=13",
     "sonner": ">=1.7",
     "zustand": ">=5",
-    "@asteby/metacore-sdk": "^3.2.0",
-    "@asteby/metacore-ui": "^2.10.0"
+    "@asteby/metacore-sdk": "^3.2.1",
+    "@asteby/metacore-ui": "^2.10.1"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-router": {
@@ -67,8 +67,8 @@
     "typescript": "^6.0.0",
     "vitest": "^4.0.0",
     "zustand": "^5.0.0",
-    "@asteby/metacore-sdk": "3.2.0",
-    "@asteby/metacore-ui": "2.10.0"
+    "@asteby/metacore-sdk": "3.2.1",
+    "@asteby/metacore-ui": "2.10.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/collection-cell.tsx

@@ -92,6 +92,8 @@ interface ResolvedRef {
     value?: unknown
     /** Optional thumbnail (product photo, logo, avatar) resolved by the backend. */
     image?: string
+    /** Optional secondary identifier (SKU/email) shown muted under the label. */
+    subtitle?: string
 }
 
 /**
@@ -110,6 +112,7 @@ function resolvedRefFor(
         const obj = sibling as Record<string, unknown>
         const label = obj.label
         if (label !== undefined && label !== null && label !== '') {
+            const sub = obj.subtitle ?? obj.description
             return {
                 label: String(label),
                 value: obj.value,
@@ -117,6 +120,10 @@ function resolvedRefFor(
                     typeof obj.image === 'string' && obj.image !== ''
                         ? obj.image
                         : undefined,
+                subtitle:
+                    sub !== undefined && sub !== null && sub !== ''
+                        ? String(sub)
+                        : undefined,
             }
         }
     } else if (typeof sibling === 'string' && sibling !== '') {
@@ -148,11 +155,14 @@ function resolvedRefObject(
     if (!isPlainObject(v)) return null
     const label = v.label
     if (label === undefined || label === null || label === '') return null
+    const sub = v.subtitle ?? v.description
     return {
         label: String(label),
         value: v.value,
         image:
             typeof v.image === 'string' && v.image !== '' ? v.image : undefined,
+        subtitle:
+            sub !== undefined && sub !== null && sub !== '' ? String(sub) : undefined,
     }
 }
 
@@ -165,23 +175,26 @@ function resolvedRefObject(
 function RefChip({
     label,
     image,
+    subtitle,
     getImageUrl,
 }: {
     label: string
     image?: string
+    subtitle?: string
     getImageUrl?: (path: string) => string
 }): React.ReactElement {
     const isDark = useIsDarkTheme()
+    const size = subtitle ? 24 : 18
     return (
         <span
             className="inline-flex max-w-[220px] items-center gap-1.5 rounded-md px-2 py-0.5 text-xs font-medium"
             style={relationChipStyles(label, { isDark })}
-            title={label}
+            title={subtitle ? `${label} · ${subtitle}` : label}
         >
             {image ? (
                 <Avatar
                     className="shrink-0 rounded-sm ring-1 ring-border/40"
-                    style={{ width: 18, height: 18 }}
+                    style={{ width: size, height: size }}
                 >
                     <AvatarImage
                         src={getImageUrl ? getImageUrl(image) : image}
@@ -195,7 +208,14 @@ function RefChip({
             ) : (
                 <Box className="h-3 w-3 shrink-0 opacity-70" />
             )}
-            <span className="truncate">{label}</span>
+            {subtitle ? (
+                <span className="flex flex-col leading-tight min-w-0">
+                    <span className="truncate">{label}</span>
+                    <span className="truncate text-[0.65rem] opacity-70">{subtitle}</span>
+                </span>
+            ) : (
+                <span className="truncate">{label}</span>
+            )}
         </span>
     )
 }
@@ -218,7 +238,7 @@ function ItemFieldCell({
     const ref = resolvedRefFor(field, row)
     if (ref?.label) {
         return (
-            <RefChip label={ref.label} image={ref.image} getImageUrl={getImageUrl} />
+            <RefChip label={ref.label} image={ref.image} subtitle={ref.subtitle} getImageUrl={getImageUrl} />
         )
     }
     return <>{formatScalar(row[field.key])}</>
@@ -495,6 +515,7 @@ function MiniTable({
                                         <RefChip
                                             label={ref.label}
                                             image={ref.image}
+                                            subtitle={ref.subtitle}
                                             getImageUrl={getImageUrl}
                                         />
                                     ) : (

package/src/display-value.tsx

@@ -98,6 +98,15 @@ export interface DisplayOption {
     icon?: string
     color?: string
     image?: string
+    /**
+     * Secondary identifier shown UNDER the label (muted, smaller) — a product's
+     * SKU/barcode, a user's email, etc. Lets a reference chip read like
+     * "Camiseta / SKU-001" instead of a bare name, so a resolved record is
+     * unambiguous. Populated declaratively: the backend projects it as the
+     * option/relation `description` (SearchConfig/FieldOptionsConfig.Description,
+     * or a column's `label_description`). Absent → single-line label as before.
+     */
+    subtitle?: string
 }
 
 /**
@@ -123,12 +132,23 @@ export const OptionBadge: React.FC<{
                     src={option.image}
                     alt={option.label}
                     getImageUrl={getImageUrl}
-                    size={16}
+                    size={option.subtitle ? 22 : 16}
                 />
             ) : (
                 option.icon && <DynamicIcon name={option.icon} className="h-3.5 w-3.5" />
             )}
-            <span>{option.label}</span>
+            {option.subtitle ? (
+                // Two-line identity: label on top, the secondary identifier
+                // (SKU/email/…) muted underneath. `leading-tight` keeps the pill
+                // compact; the subtitle inherits the badge's fg at reduced opacity
+                // so it reads as secondary on any color.
+                <span className="flex flex-col leading-tight text-start">
+                    <span>{option.label}</span>
+                    <span className="text-[0.7rem] opacity-70">{option.subtitle}</span>
+                </span>
+            ) : (
+                <span>{option.label}</span>
+            )}
         </Badge>
     )
 }

package/src/dynamic-columns.tsx

@@ -332,7 +332,10 @@ const BadgeWithEndpointOptions: React.FC<{
     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)} getImageUrl={getImageUrl} />
+    // Reference options carry the backend-projected `description` (the SKU/email
+    // the author pointed the options config at) — surface it as the chip subtitle
+    // so a resolved record reads "Name / SKU" instead of a bare name.
+    if (option) return <OptionBadge option={{ ...option, subtitle: option.subtitle ?? (option as any).description }} 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>
@@ -461,6 +464,23 @@ export const resolveRelationImage = (col: ColumnDefinition, row: any): string =>
     return ''
 }
 
+/**
+ * Reads a secondary identifier the backend stamps on a resolved FK sibling — a
+ * product's SKU, a user's email — projected as `subtitle`/`description` (the
+ * relational twin of `image` via the column's `label_description`). Rendered
+ * muted under the label so a reference chip reads "Name / SKU". Domain-agnostic:
+ * only the generic `subtitle`/`description` keys are read (never a hardcoded
+ * `sku`/`code`), so the author picks the column declaratively. '' when absent.
+ */
+export const resolveRelationSubtitle = (col: ColumnDefinition, row: any): string => {
+    const sibling = getNestedValue(row, relationKeyFor(col))
+    if (sibling && typeof sibling === 'object') {
+        const sub = sibling.subtitle ?? sibling.description
+        if (sub !== undefined && sub !== null && sub !== '') return String(sub)
+    }
+    return ''
+}
+
 /**
  * Renders a resolved FK relation as a clean, truncated chip. Reads the
  * backend-resolved sibling `{ value, label[, image] }` (see `relationKeyFor`)
@@ -478,6 +498,7 @@ const RelationCell: React.FC<{
     const display = resolveRelationLabel(col, row)
     if (!display) return <EmptyCell />
     const image = resolveRelationImage(col, row)
+    const subtitle = resolveRelationSubtitle(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
@@ -487,12 +508,19 @@ const RelationCell: React.FC<{
         <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}
+            title={subtitle ? `${display} · ${subtitle}` : display}
         >
             {image && (
-                <RelationThumbnail src={image} alt={display} getImageUrl={getImageUrl} size={18} />
+                <RelationThumbnail src={image} alt={display} getImageUrl={getImageUrl} size={subtitle ? 24 : 18} />
+            )}
+            {subtitle ? (
+                <span className="flex flex-col leading-tight min-w-0">
+                    <span className="truncate">{display}</span>
+                    <span className="truncate text-[0.7rem] opacity-70">{subtitle}</span>
+                </span>
+            ) : (
+                <span className="truncate">{display}</span>
             )}
-            <span className="truncate">{display}</span>
         </span>
     )
 }