@asteby/metacore-runtime-react 34.1.0 → 35.0.0

package/src/action-modal-dispatcher.tsx

@@ -156,6 +156,65 @@ export function buildPrefillRows(spec: PrefillSpec, record: any): Array<Record<s
     return rows
 }
 
+// ---- scalar prefill from the acted-on record --------------------------------
+//
+// Row actions (stamp / refactura / cancel-with-reason) should open with the
+// current record's values, not empty selects. Manifest declares explicit paths
+// via `defaultFromRecord` (string or string[] fallback chain). When omitted,
+// the field seeds from record[field.key] if present.
+
+export function unwrapRecordScalar(value: unknown): unknown {
+    if (value === null || value === undefined) return value
+    if (typeof value !== 'object' || value instanceof Date) return value
+    if (Array.isArray(value)) return value
+    const o = value as Record<string, unknown>
+    if ('value' in o && (typeof o.value === 'string' || typeof o.value === 'number')) {
+        return o.value
+    }
+    if ('id' in o && (typeof o.id === 'string' || typeof o.id === 'number')) {
+        return o.id
+    }
+    return value
+}
+
+export function readRecordPath(record: any, path: string): unknown {
+    if (!record || !path) return undefined
+    const parts = path.split('.')
+    let cur: any = record
+    for (const p of parts) {
+        if (cur == null || typeof cur !== 'object') return undefined
+        cur = cur[p]
+    }
+    return unwrapRecordScalar(cur)
+}
+
+function defaultFromRecordSpec(field: ActionFieldDef): string | string[] | undefined {
+    const f = field as ActionFieldDef & {
+        defaultFromRecord?: string | string[]
+        default_from_record?: string | string[]
+    }
+    return f.defaultFromRecord ?? f.default_from_record
+}
+
+/** Scalar seed for one action field from the row being acted on. */
+export function scalarDefaultFromRecord(field: ActionFieldDef, record: any): unknown {
+    if (!record) return undefined
+    const spec = defaultFromRecordSpec(field)
+    if (typeof spec === 'string') {
+        const v = readRecordPath(record, spec)
+        if (v !== undefined && v !== null && v !== '') return v
+    } else if (Array.isArray(spec)) {
+        for (const path of spec) {
+            const v = readRecordPath(record, path)
+            if (v !== undefined && v !== null && v !== '') return v
+        }
+    } else if (field.key) {
+        const v = readRecordPath(record, field.key)
+        if (v !== undefined && v !== null && v !== '') return v
+    }
+    return undefined
+}
+
 export function ActionModalDispatcher({
     open,
     onOpenChange,
@@ -322,14 +381,17 @@ function selectPreviewColumns(columns: ColumnDefinition[] | undefined, record: a
             continue
         }
 
-        // Relación (ref / search / dynamic_select / *_id): solo si el sibling
-        // resolvió a un label legible; si es un *_id crudo sin resolver, se omite.
+        // Relación (ref / search / dynamic_select / uuid *_id): solo si el sibling
+        // resolvió a un label legible; text `*_id` (external_id) no es FK.
+        const t = String(col.type || '').toLowerCase()
         const isRelation =
             !!getFieldRef(col as ActionFieldDef) ||
             col.type === 'search' ||
             col.type === 'relation' ||
             (col as { widget?: string }).widget === 'dynamic_select' ||
-            (typeof col.key === 'string' && col.key.endsWith('_id'))
+            (typeof col.key === 'string' &&
+                col.key.endsWith('_id') &&
+                (t === 'uuid' || t === 'search' || t === 'relation' || t === 'dynamic_select' || t === 'belongs_to'))
         if (isRelation) {
             const sib = relationSiblingValue(col as any, record)
             const label = typeof sib === 'string' ? sib : objectLabel(sib)
@@ -552,20 +614,7 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
 
     useEffect(() => {
         if (open && action.fields) {
-            const defaults: Record<string, any> = {}
-            for (const field of action.fields) {
-                if (isLineItemsField(field)) {
-                    const dv = lineItemsDefault(field)
-                    defaults[field.key] = isPrefillSpec(dv)
-                        ? buildPrefillRows(dv, record)
-                        : Array.isArray(dv)
-                          ? dv
-                          : []
-                    continue
-                }
-                defaults[field.key] = field.defaultValue ?? (field.type === 'boolean' ? false : '')
-            }
-            setFormData(defaults)
+            setFormData(buildFieldDefaults(action.fields, record))
             setFieldErrors({})
         }
     }, [open, action.fields, record])
@@ -632,6 +681,8 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
         () => (action.fields ?? []).some(isLineItemsField),
         [action.fields],
     )
+    const embedRelations =
+        hasLineItems || !!(action as ActionMetadata & { embedRelations?: boolean }).embedRelations
     const explicitWidth = (action as unknown as { modalWidth?: number | string }).modalWidth
     const widthPx =
         explicitWidth != null
@@ -657,7 +708,7 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
                         <DynamicIcon name={action.icon} className="h-5 w-5" />
                         {tl(action.label)}
                     </DialogTitle>
-                    {action.confirmMessage && <DialogDescription>{action.confirmMessage}</DialogDescription>}
+                    {action.confirmMessage && <DialogDescription>{tl(action.confirmMessage)}</DialogDescription>}
                 </DialogHeader>
                 {/* Scrollable body. The shared FieldGrid lays scalar fields out
                     in two responsive columns (single column on phones); line-items
@@ -676,14 +727,14 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
                                     <FieldLabel htmlFor={field.key} required={field.required}>
                                         {tl(field.label)}
                                     </FieldLabel>
-                                    {renderField(field, formData[field.key], (v: any) => updateField(field.key, v), formData)}
+                                    {renderField(field, formData[field.key], (v: any) => updateField(field.key, v), formData, record)}
                                     {fieldErrors[field.key] && (
                                         <p className="text-destructive text-xs mt-1">{fieldErrors[field.key]}</p>
                                     )}
                                 </FieldCell>
                             )
                         })}
-                        {relations.length > 0 && (
+                        {embedRelations && relations.length > 0 && (
                             <FieldCell fullWidth>
                                 {/* Igual que el modal de registro: solo las
                                     relaciones de composición se embeben. */}
@@ -725,6 +776,11 @@ function buildFieldDefaults(fields: ActionFieldDef[], record: any): Record<strin
                   : []
             continue
         }
+        const fromRecord = scalarDefaultFromRecord(field, record)
+        if (fromRecord !== undefined && fromRecord !== null && fromRecord !== '') {
+            defaults[field.key] = fromRecord
+            continue
+        }
         defaults[field.key] = field.defaultValue ?? (field.type === 'boolean' ? false : '')
     }
     return defaults
@@ -881,7 +937,7 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
                                     <FieldLabel htmlFor={field.key} required={field.required}>
                                         {tl(field.label)}
                                     </FieldLabel>
-                                    {renderField(field, formData[field.key], (v: any) => updateField(field.key, v), formData)}
+                                    {renderField(field, formData[field.key], (v: any) => updateField(field.key, v), formData, record)}
                                 </FieldCell>
                             )
                         })}
@@ -922,6 +978,29 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
     )
 }
 
+function seedOptionFromRecord(
+    field: ActionFieldDef,
+    value: any,
+    record?: Record<string, any>,
+): import('./use-options-resolver').ResolvedOption | undefined {
+    if (!record || !field.key.endsWith('_id')) return undefined
+    const siblingKey = field.key.replace(/_id$/, '')
+    const sib = record[siblingKey]
+    if (!sib || typeof sib !== 'object') return undefined
+    const label = (sib as any).label ?? (sib as any).name ?? ''
+    if (!label && !(sib as any).image) return undefined
+    const id = String((sib as any).value ?? (sib as any).id ?? value ?? '')
+    return {
+        id,
+        value: id,
+        label: String(label),
+        name: String(label),
+        image: (sib as any).image,
+        color: (sib as any).color,
+        icon: (sib as any).icon,
+    }
+}
+
 function renderField(
     field: ActionFieldDef,
     value: any,
@@ -931,6 +1010,7 @@ function renderField(
     // fields. Omitted by callers that have no surrounding form (the field is
     // then treated as having no resolvable dependency).
     formValues?: Record<string, any>,
+    record?: Record<string, any>,
 ) {
     // Repeatable line-items group → row grid (value is an array of row objects).
     // The header form values flow in so a cell can depend on a header field.
@@ -948,7 +1028,15 @@ function renderField(
         const dependsValue = getDependsOn(field)
             ? resolveDependsValue(field, formValues)
             : undefined
-        return <DynamicSelectField field={field} value={value} onChange={onChange} dependsValue={dependsValue} />
+        return (
+            <DynamicSelectField
+                field={field}
+                value={value}
+                onChange={onChange}
+                dependsValue={dependsValue}
+                seedOption={seedOptionFromRecord(field, value, record)}
+            />
+        )
     }
     // File upload → themed picker that POSTs the file to the host upload
     // endpoint and stores the returned url/path. Kept in sync with DynamicForm.

package/src/addon-loader.tsx

@@ -199,7 +199,13 @@ export function AddonLoader({
     }, [scope, url, module, addonKey, unbindKey, hostRegistry])
 
     if (status === 'loading') return <>{fallback}</>
-    if (status === 'error')
+    if (status === 'error') {
+        // Hosts that pass `onError` (toast + telemetry) should not also paint
+        // a second, persistent inline banner — DynamicAddonLoaders mounts one
+        // fiber per installed addon and a visible error stack reads as a broken
+        // shell even when only one remote failed transiently.
+        if (onError) return null
         return <div className="text-sm text-red-500">Addon load error: {error?.message}</div>
+    }
     return <>{children}</>
 }

package/src/dialogs/dynamic-record.tsx

@@ -9,7 +9,7 @@
 // flows through <ApiProvider> from runtime-react. Host-specific runtime values —
 // the image-url resolver and the org IANA timezone — are passed as props so the
 // SDK stays transport- and host-agnostic.
-import { createContext, useCallback, useContext, useEffect, useId, useRef, useState } from 'react'
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import type { ModelSchema } from './types'
 
@@ -53,9 +53,7 @@ import { es } from 'date-fns/locale'
 import { ExternalLink, Loader2, CalendarIcon, ChevronDown, Check, Upload, X as XIcon, ScanLine } from 'lucide-react'
 import { BarcodeScanner } from '../barcode-scanner'
 import { useApi } from '../api-context'
-import { toastServerError, extractFieldErrors, localizeFieldErrorMap, type Translate } from '../server-error'
-import { validateValues, bagHasErrors } from '../validator'
-import { validationCatalog } from '../validation-catalog'
+import { toastServerError, extractFieldErrors, localizeFieldIssue } from '../server-error'
 import { DynamicSelectField, OptionLead, OptionThumb } from '../dynamic-select-field'
 import { DynamicRelations } from '../dynamic-relations'
 import { useOptionsResolver, type ResolvedOption } from '../use-options-resolver'
@@ -421,6 +419,24 @@ function isRelationField(field: FieldDef): boolean {
     )
 }
 
+// looksLikeForeignKey — true only for real FKs. A bare `*_id` suffix is NOT
+// enough: columns like `external_id`, `trace_id`, or `invoice_uid` are plain
+// text identifiers from a PAC/provider, not belongs_to relations. Treating them
+// as relations rendered an InitialsAvatar ("6" chip next to "6a8c…") and made
+// fiscal detail modals look broken.
+function looksLikeForeignKey(field: FieldDef): boolean {
+    if (isRelationField(field)) return true
+    if (typeof field.key !== 'string' || !field.key.endsWith('_id')) return false
+    const t = String(field.type || '').toLowerCase()
+    return (
+        t === 'uuid' ||
+        t === 'search' ||
+        t === 'relation' ||
+        t === 'dynamic_select' ||
+        t === 'belongs_to'
+    )
+}
+
 function formatDisplayValue(rawValue: any, field: FieldDef): string {
     // Unset nullable FK serialized as the nil UUID renders as empty, not zeros.
     const value = normalizeNilUuid(rawValue)
@@ -544,12 +560,6 @@ export function stripHiddenFieldValues(
     return out
 }
 
-function toastValidationFailed(t: Translate, lang: string, localized: Record<string, string>) {
-    toast.error(t('validation.failed', { defaultValue: validationCatalog(lang).failed }), {
-        description: Object.values(localized).filter(Boolean).join('\n'),
-    })
-}
-
 export function DynamicRecordDialog({
     open,
     onOpenChange,
@@ -573,12 +583,7 @@ export function DynamicRecordDialog({
     onChange,
 }: DynamicRecordDialogProps) {
     const api = useApi()
-    const { t, i18n } = useTranslation()
-    // Unique per dialog instance. The footer submit lives OUTSIDE <form>, so
-    // it binds via `form={id}`. A hardcoded id made nested create (product +
-    // "Crear categoría") submit the PARENT form — toast "Revisa los campos
-    // marcados" with no marks on the inner modal.
-    const formId = useId()
+    const { t } = useTranslation()
     const [modalMeta, setModalMeta] = useState<ModalMetadata | null>(
         schema ? (schema as ModalMetadata) : null,
     )
@@ -779,26 +784,25 @@ export function DynamicRecordDialog({
     // with no matching form field).
     const labelForKey = (key: string): string => {
         const f = (modalMeta?.fields ?? []).find(x => x.key === key)
-        if (f?.label) return t(f.label, { defaultValue: f.label })
+        if (f?.label) return f.label
         return key.replace(/[._-]+/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
     }
 
-    const lang = i18n.language
-
     // Turn a failed submit (422 `errors` map, or a bare `{errors}` body) into
     // inline field errors + a summary toast. When there is no field map, fall
     // back to the existing single cause-carrying toast.
     const handleSubmitError = (err: unknown) => {
         const map = extractFieldErrors(err)
         if (map) {
-            const labels: Record<string, string> = {}
-            for (const f of modalMeta?.fields ?? []) labels[f.key] = labelForKey(f.key)
-            const localized = localizeFieldErrorMap(map, t, { labels, language: lang })
-            setFieldErrors(localized)
-            toastValidationFailed(t, lang, localized)
+            const next: Record<string, string> = {}
+            for (const [key, issues] of Object.entries(map)) {
+                next[key] = localizeFieldIssue(issues[0], labelForKey(key), t)
+            }
+            setFieldErrors(next)
+            toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
             return
         }
-        toastServerError(err, { t, language: lang, fallback: t('dynamic.save_error', { defaultValue: 'No se pudo guardar' }) })
+        toastServerError(err, { t, fallback: t('dynamic.save_error', { defaultValue: 'No se pudo guardar' }) })
     }
 
     const handleSubmit = async (e?: React.FormEvent) => {
@@ -811,14 +815,15 @@ export function DynamicRecordDialog({
             // fields are gated: a field hidden by its `visible_when` predicate
             // must not block submit even when it is declared required (matching
             // the render, which drops it via the same filter).
-            const visible = filterVisibleFields(modalMeta.fields, mode, formValues)
-            const bag = validateValues(visible as ActionFieldDef[], formValues)
-            if (bagHasErrors(bag)) {
-                const labels: Record<string, string> = {}
-                for (const f of visible) labels[f.key] = t(f.label, { defaultValue: f.label })
-                const localized = localizeFieldErrorMap(bag, t, { labels, language: lang })
-                setFieldErrors(localized)
-                toastValidationFailed(t, lang, localized)
+            const missing: Record<string, string> = {}
+            for (const field of filterVisibleFields(modalMeta.fields, mode, formValues)) {
+                if (field.required && !formValues[field.key] && formValues[field.key] !== 0 && formValues[field.key] !== false) {
+                    missing[field.key] = localizeFieldIssue({ code: 'required' }, field.label, t)
+                }
+            }
+            if (Object.keys(missing).length) {
+                setFieldErrors(missing)
+                toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
                 return
             }
         }
@@ -960,13 +965,15 @@ export function DynamicRecordDialog({
     // then advance. Mirrors handleSubmit's required check but scoped to the step.
     const goNextStep = () => {
         const step = groups[clampedStep]
-        const bag = validateValues((step?.fields ?? []) as ActionFieldDef[], formValues)
-        if (bagHasErrors(bag)) {
-            const labels: Record<string, string> = {}
-            for (const f of step?.fields ?? []) labels[f.key] = t(f.label, { defaultValue: f.label })
-            const localized = localizeFieldErrorMap(bag, t, { labels, language: lang })
-            setFieldErrors(localized)
-            toastValidationFailed(t, lang, localized)
+        const missing: Record<string, string> = {}
+        for (const field of step?.fields ?? []) {
+            if (field.required && !formValues[field.key] && formValues[field.key] !== 0 && formValues[field.key] !== false) {
+                missing[field.key] = localizeFieldIssue({ code: 'required' }, field.label, t)
+            }
+        }
+        if (Object.keys(missing).length) {
+            setFieldErrors(missing)
+            toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
             return
         }
         setFieldErrors({})
@@ -999,7 +1006,7 @@ export function DynamicRecordDialog({
                                 cell `min-w-0` so a long select/input value can't
                                 blow the two columns past the dialog width. */}
                             <form
-                                id={formId}
+                                id="dynamic-record-form"
                                 onSubmit={handleSubmit}
                                 className="grid gap-y-4"
                             >
@@ -1109,7 +1116,7 @@ export function DynamicRecordDialog({
                         {isEditable && (!isSteps || isLastStep) && (
                             <Button
                                 type="submit"
-                                form={formId}
+                                form="dynamic-record-form"
                                 disabled={saving || loading}
                             >
                                 {saving && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
@@ -1213,9 +1220,7 @@ export function ReadonlyEditField({ field, value }: { field: FieldDef; value: an
 // ReadonlyRelationField — a locked/readonly FK field (customer_id, category_id…)
 // resolves the record's label instead of showing the raw id, mirroring
 // RelationViewValue's lookup but rendered as a disabled input to match the rest
-// of ReadonlyEditField. Without this, a locked relation field (e.g. `lockedFields`
-// seeding a POS-selected customer into a vehicle create modal) would show a bare
-// UUID — the exact readability bug this dialog otherwise avoids elsewhere.
+// of ReadonlyEditField.
 function ReadonlyRelationField({
     field,
     value,
@@ -1244,7 +1249,19 @@ function ReadonlyRelationField({
 // RelationViewValue — read-only FK lead. Resolves the relation's label + image
 // from (1) the sibling object the table served, then (2) the canonical options
 // endpoint, and renders an OptionLead (thumbnail / icon / color dot) + label.
-function RelationViewValue({ field, value, record, stack = false }: { field: FieldDef; value: any; record: any; stack?: boolean }) {
+// When `stack` is true (`display: "image_stack"`), the landscape mark sits ON
+// TOP of the label — wide logos (brand marks) fit without cropping.
+function RelationViewValue({
+    field,
+    value,
+    record,
+    stack = false,
+}: {
+    field: FieldDef
+    value: any
+    record: any
+    stack?: boolean
+}) {
     const getImageUrl = useContext(ImageUrlContext)
     const sib = relationSiblingValue(field, record)
     const sibLabel = typeof sib === 'string' ? sib : objectLabel(sib)
@@ -1382,18 +1399,16 @@ export function ViewValue({
 
     const value = normalizeNilUuid(rawValue)
 
-    // Landscape stack on a relation FK (brand marks, product cards).
-    if (
-        renderAs === 'image_stack' &&
-        (isRelationField(field) || (typeof field.key === 'string' && field.key.endsWith('_id')))
-    ) {
+    // Landscape stack on a relation FK (brand marks, product cards): image ON
+    // TOP, label UNDERNEATH. Checked before the default relation lead so a
+    // `display: "image_stack"` FK does not fall through to the side-by-side chip.
+    if (renderAs === 'image_stack' && looksLikeForeignKey(field)) {
         return <RelationViewValue field={field} value={value} record={record} stack />
     }
 
-    // Relation (search / dynamic_select / ref / any *_id) → resolved thumbnail +
-    // label. The *_id catch-all covers plain-typed FK columns not tagged as a
-    // relation field.
-    if (isRelationField(field) || (typeof field.key === 'string' && field.key.endsWith('_id'))) {
+    // Relation (search / dynamic_select / ref / uuid *_id FK) → resolved
+    // thumbnail + label. Plain text `*_id` columns (external_id, …) stay text.
+    if (looksLikeForeignKey(field)) {
         return <RelationViewValue field={field} value={value} record={record} />
     }
 
@@ -1426,27 +1441,36 @@ export function ViewValue({
         )
     }
 
-    // Landscape stack for image/logo URL columns.
+    // Landscape stack for image/logo URL columns (and `type: image` with
+    // `cellStyle: image_stack`). Wide marks sit above an optional caption.
     if (renderAs === 'image_stack') {
-        const caption =
-            (typeof field.styleConfig?.label_field === 'string' &&
-                record?.[field.styleConfig.label_field]) ||
-            (typeof field.styleConfig?.labelField === 'string' &&
-                record?.[field.styleConfig.labelField]) ||
-            undefined
-        return (
+        if (value && isLucideIconName(value)) {
+            return <IconNameViewValue name={value} />
+        }
+        const labelField =
+            (field.styleConfig &&
+                (field.styleConfig.label_field as string | undefined)) ||
+            (field.styleConfig && (field.styleConfig.labelField as string | undefined))
+        let caption: string | undefined
+        if (labelField && record && typeof record === 'object') {
+            const raw = (record as Record<string, unknown>)[labelField]
+            if (raw != null && String(raw) !== '') caption = String(raw)
+        }
+        return value || caption ? (
             <div className="py-1">
                 <ImageStack
                     src={value ? String(value) : undefined}
-                    label={caption ? String(caption) : field.label}
+                    label={caption}
                     getImageUrl={getImageUrl}
                     size="lg"
                 />
             </div>
+        ) : (
+            <p className="text-sm py-1 text-muted-foreground">Sin imagen</p>
         )
     }
 
-    if (field.type === 'image') {
+    if (field.type === 'image' || renderAs === 'image') {
         if (isLucideIconName(value)) {
             return <IconNameViewValue name={value} />
         }
@@ -1740,6 +1764,19 @@ function StructuredViewValue({
     if (isEmpty) {
         return <p className="text-sm py-1 text-muted-foreground">—</p>
     }
+    // Line-items arrays with a declared itemFields schema → mini-table.
+    // Plain objects (PAC provider_data, fiscal_data bags) → readable key/value
+    // list; nested objects/arrays render as pretty JSON instead of `key: {…}`
+    // stubs that looked broken in fiscal detail modals.
+    const hasItemFields = !!(field?.itemFields ?? field?.item_fields)
+    if (
+        !hasItemFields &&
+        value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value)
+    ) {
+        return <JsonObjectViewValue value={value as Record<string, unknown>} />
+    }
     return (
         <div className="text-sm py-1">
             <CollectionCell
@@ -1754,6 +1791,43 @@ function StructuredViewValue({
     )
 }
 
+/** Flatten a jsonb/object bag into labeled rows; nest as pretty JSON. */
+function JsonObjectViewValue({ value }: { value: Record<string, unknown> }) {
+    const entries = Object.entries(value).filter(([, v]) => v !== undefined)
+    if (entries.length === 0) {
+        return <p className="text-sm py-1 text-muted-foreground">—</p>
+    }
+    return (
+        <dl className="grid gap-2 py-1 text-sm">
+            {entries.map(([key, raw]) => {
+                const label = humanizeToken(key)
+                const isNest =
+                    raw !== null &&
+                    typeof raw === 'object' &&
+                    !(raw instanceof Date)
+                return (
+                    <div key={key} className="min-w-0">
+                        <dt className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
+                            {label}
+                        </dt>
+                        <dd className="mt-0.5 break-words text-foreground">
+                            {isNest ? (
+                                <pre className="max-h-48 overflow-auto rounded-md bg-muted/40 p-2 text-[11px] leading-relaxed whitespace-pre-wrap">
+                                    {JSON.stringify(raw, null, 2)}
+                                </pre>
+                            ) : raw === null || raw === '' ? (
+                                <span className="text-muted-foreground">—</span>
+                            ) : (
+                                String(raw)
+                            )}
+                        </dd>
+                    </div>
+                )
+            })}
+        </dl>
+    )
+}
+
 export function EditField({ field, value, onChange, record }: {
     field: FieldDef
     value: any

package/src/dynamic-columns.tsx

@@ -44,9 +44,10 @@ import {
 import { Progress } from './dialogs/_primitives'
 import { humanizeToken } from './dynamic-columns-helpers'
 import { objectLabel } from './dynamic-relation-helpers'
-import { ImageStack,
+import {
     OptionBadge,
     RelationThumbnail,
+    ImageStack,
     statusColorFor,
     useIsDarkTheme,
 } from './display-value'
@@ -603,6 +604,10 @@ export const resolveRelationSubtitle = (col: ColumnDefinition, row: any): string
  * 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.
+ *
+ * When `stack` is true (column `display: "image_stack"`), the landscape mark
+ * sits ON TOP of the label — wide logos fit without cropping and the cell
+ * stays readable in dense tables.
  */
 const RelationCell: React.FC<{
     col: ColumnDefinition
@@ -944,7 +949,15 @@ export function makeDefaultGetDynamicColumns(
                     }
 
                     // Landscape stack: wide image ON TOP, label UNDERNEATH.
+                    // Declared via `display: "image_stack"` on an image column
+                    // or on a belongs_to FK whose sibling carries a logo/photo
+                    // (brand marks, product cards). Fits logos that are wider
+                    // than tall without cropping into a square thumb.
                     if (renderAs === 'image_stack') {
+                        // FK relation (brand_id → brands) OR any column that
+                        // already resolved a sibling with an image — stack it.
+                        // Don't require `col.ref` alone: enrichment sometimes
+                        // leaves type=text while cellStyle carries image_stack.
                         const looksRelation =
                             !!col.ref ||
                             (typeof col.key === 'string' &&
@@ -1332,30 +1345,33 @@ export function makeDefaultGetDynamicColumns(
                             )
                         }
 
-                        case 'image_stack': {
+                        case 'image': {
                             const imageValue =
                                 value ||
                                 (Array.isArray(row.original.media)
                                     ? row.original.media.find((m: any) => m.type === 'image')?.url
                                     : null)
+                            return <ImageCell value={imageValue} getImageUrl={getImageUrl} />
+                        }
+
+                        case 'image_stack': {
+                            // Defensive: normally handled above before the
+                            // switch; kept so a late `type: image_stack` without
+                            // cellStyle still stacks.
+                            const labelField = styleCfg(col, 'label_field', 'labelField')
+                            const caption = labelField
+                                ? String(getNestedValue(row.original, labelField) ?? '')
+                                : undefined
                             return (
                                 <ImageCell
-                                    value={imageValue}
+                                    value={value}
                                     getImageUrl={getImageUrl}
+                                    label={caption || undefined}
                                     stack
                                 />
                             )
                         }
 
-                        case 'image': {
-                            const imageValue =
-                                value ||
-                                (Array.isArray(row.original.media)
-                                    ? row.original.media.find((m: any) => m.type === 'image')?.url
-                                    : null)
-                            return <ImageCell value={imageValue} getImageUrl={getImageUrl} />
-                        }
-
                         default: {
                             if (typeof value === 'object' && value !== null) {
                                 return (