@asteby/metacore-runtime-react 25.1.2 → 25.1.4

package/dist/server-error.js

@@ -59,6 +59,72 @@ export function extractServerError(err, fallbackTitle) {
         return { title: fallbackTitle, description: raw.trim() };
     return { title: fallbackTitle };
 }
+/** Spanish defaults per known validation code. `{{label}}` (and code params like
+ *  `allowed`/`ref`/`expected`) are interpolated by i18next, so a host can override
+ *  any of these via its addon i18n bundle under `validation.<code>`. */
+const VALIDATION_DEFAULTS = {
+    required: 'El campo {{label}} es obligatorio',
+    invalid_option: 'El valor de {{label}} no es válido',
+    not_found: 'El {{label}} seleccionado no existe',
+    duplicate: 'Ya existe un registro con ese {{label}}',
+    invalid_type: 'El campo {{label}} tiene un formato inválido',
+};
+const VALIDATION_FALLBACK = '{{label}}: valor inválido';
+/** Normalize one raw `errors` value entry into a `FieldIssue`.
+ *  A string → `{message}` (pre-localized, shown verbatim); an object → `{code,params}`. */
+function toFieldIssue(entry) {
+    if (typeof entry === 'string') {
+        const s = entry.trim();
+        return s ? { message: s } : undefined;
+    }
+    if (entry && typeof entry === 'object') {
+        const e = entry;
+        if (typeof e.message === 'string' && e.message.trim())
+            return { message: e.message.trim() };
+        if (typeof e.code === 'string' && e.code) {
+            return {
+                code: e.code,
+                params: e.params && typeof e.params === 'object' ? e.params : undefined,
+            };
+        }
+    }
+    return undefined;
+}
+/**
+ * Pull the per-field `errors` map out of an axios error (`err.response.data.errors`)
+ * or a bare response body (`{ errors }`), normalizing each field's value to a
+ * `FieldIssue[]`. A value may be a single entry or an array; string entries become
+ * `{message}`, object entries `{code,params}`. Returns `undefined` when there is no
+ * usable map (no `errors`, or nothing normalized). Pure — no i18n, no toast.
+ */
+export function extractFieldErrors(err) {
+    const maybeAxios = err?.response?.data;
+    const data = maybeAxios ?? err;
+    const errors = data?.errors;
+    if (!errors || typeof errors !== 'object' || Array.isArray(errors))
+        return undefined;
+    const out = {};
+    for (const [key, raw] of Object.entries(errors)) {
+        const entries = Array.isArray(raw) ? raw : [raw];
+        const issues = entries.map(toFieldIssue).filter((i) => !!i);
+        if (issues.length)
+            out[key] = issues;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/**
+ * Localize a single `FieldIssue` to a human, Spanish-by-default string using the
+ * field `label`. A pre-localized `message` passes through verbatim. Otherwise the
+ * `code` is translated via `t('validation.'+code, { defaultValue, label, ...params })`
+ * so hosts can override the copy and `{{label}}`/param interpolation still works.
+ */
+export function localizeFieldIssue(issue, label, t) {
+    if (issue.message)
+        return issue.message;
+    const code = issue.code ?? '';
+    const defaultValue = VALIDATION_DEFAULTS[code] ?? VALIDATION_FALLBACK;
+    return t(`validation.${code}`, { defaultValue, label, ...(issue.params ?? {}) });
+}
 /** A dotted, space-free token (e.g. "pos.rate.created") — the shape of an i18n
  *  key, as opposed to human prose ("Record created successfully"). Used to
  *  decide whether a server-sent message is safe to translate or should be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "25.1.2",
+  "version": "25.1.4",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",

package/src/__tests__/extract-field-errors.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest'
+import { extractFieldErrors, localizeFieldIssue, type FieldIssue } from '../server-error'
+
+// A minimal i18next-like translator: honors defaultValue and does {{var}}
+// interpolation, so the tests assert BOTH the resolved Spanish default and that
+// the field label / code params are interpolated.
+const t = (_key: string, opts?: { defaultValue?: string; [k: string]: unknown }) => {
+    let out = opts?.defaultValue ?? _key
+    if (opts) {
+        for (const [k, v] of Object.entries(opts)) {
+            if (k === 'defaultValue') continue
+            out = out.replace(new RegExp(`{{\\s*${k}\\s*}}`, 'g'), String(v))
+        }
+    }
+    return out
+}
+
+describe('extractFieldErrors', () => {
+    it('normalizes object entries {code,params} from an axios error', () => {
+        const err = {
+            response: {
+                data: {
+                    success: false,
+                    message: 'validation failed',
+                    errors: { name: [{ code: 'required', params: {} }], sku: [{ code: 'duplicate' }] },
+                },
+            },
+        }
+        expect(extractFieldErrors(err)).toEqual({
+            name: [{ code: 'required', params: {} }],
+            sku: [{ code: 'duplicate', params: undefined }],
+        })
+    })
+
+    it('normalizes string entries to {message}', () => {
+        const err = { errors: { name: ['El nombre es obligatorio'], sku: 'Duplicado' } }
+        expect(extractFieldErrors(err)).toEqual({
+            name: [{ message: 'El nombre es obligatorio' }],
+            sku: [{ message: 'Duplicado' }],
+        })
+    })
+
+    it('accepts a bare response body as well as an axios error', () => {
+        const bare = { errors: { qty: [{ code: 'invalid_type', params: { expected: 'number' } }] } }
+        expect(extractFieldErrors(bare)).toEqual({
+            qty: [{ code: 'invalid_type', params: { expected: 'number' } }],
+        })
+    })
+
+    it('carries code params through (allowed / ref)', () => {
+        const err = {
+            errors: {
+                status: [{ code: 'invalid_option', params: { allowed: ['a', 'b'] } }],
+                owner: [{ code: 'not_found', params: { ref: 'users' } }],
+            },
+        }
+        expect(extractFieldErrors(err)).toEqual({
+            status: [{ code: 'invalid_option', params: { allowed: ['a', 'b'] } }],
+            owner: [{ code: 'not_found', params: { ref: 'users' } }],
+        })
+    })
+
+    it('returns undefined when there is no usable errors map', () => {
+        expect(extractFieldErrors(undefined)).toBeUndefined()
+        expect(extractFieldErrors({ response: { data: { message: 'boom' } } })).toBeUndefined()
+        expect(extractFieldErrors({ errors: 'oops' })).toBeUndefined() // string, not a map
+        expect(extractFieldErrors({ errors: ['a', 'b'] })).toBeUndefined() // array, not a map
+        expect(extractFieldErrors({ errors: {} })).toBeUndefined() // empty
+        expect(extractFieldErrors({ errors: { x: [null, ''] } })).toBeUndefined() // nothing normalizes
+    })
+})
+
+describe('localizeFieldIssue', () => {
+    it('required → interpolates label', () => {
+        expect(localizeFieldIssue({ code: 'required' }, 'Nombre', t)).toBe('El campo Nombre es obligatorio')
+    })
+    it('invalid_option', () => {
+        expect(localizeFieldIssue({ code: 'invalid_option', params: { allowed: ['a'] } }, 'Estado', t)).toBe(
+            'El valor de Estado no es válido',
+        )
+    })
+    it('not_found', () => {
+        expect(localizeFieldIssue({ code: 'not_found', params: { ref: 'users' } }, 'Responsable', t)).toBe(
+            'El Responsable seleccionado no existe',
+        )
+    })
+    it('duplicate', () => {
+        expect(localizeFieldIssue({ code: 'duplicate' }, 'SKU', t)).toBe('Ya existe un registro con ese SKU')
+    })
+    it('invalid_type', () => {
+        expect(localizeFieldIssue({ code: 'invalid_type', params: { expected: 'number' } }, 'Cantidad', t)).toBe(
+            'El campo Cantidad tiene un formato inválido',
+        )
+    })
+    it('unknown code → generic fallback with label', () => {
+        expect(localizeFieldIssue({ code: 'weird_code' }, 'Campo', t)).toBe('Campo: valor inválido')
+    })
+    it('message passthrough (pre-localized) ignores code/label', () => {
+        const issue: FieldIssue = { message: 'Texto ya localizado' }
+        expect(localizeFieldIssue(issue, 'Ignorado', t)).toBe('Texto ya localizado')
+    })
+})

package/src/__tests__/normalize-ref-fields.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest'
+import { normalizeRefFieldsForSubmit } from '../dialogs/normalize-submit'
+
+const NIL = '00000000-0000-0000-0000-000000000000'
+
+// A minimal field-metadata shape — only the keys the normalizer reads.
+const fields: any[] = [
+    { key: 'category_id', ref: 'categories' }, // reference (getFieldRef)
+    { key: 'brand_id', type: 'dynamic_select' }, // reference by type
+    { key: 'owner_id', type: 'search' }, // reference by type
+    { key: 'name', type: 'text' }, // plain scalar
+    { key: 'description', type: 'textarea' },
+]
+
+describe('normalizeRefFieldsForSubmit', () => {
+    it('nulls an empty-string reference so a nullable FK accepts it (no 23503)', () => {
+        const out = normalizeRefFieldsForSubmit(
+            { category_id: '', name: 'Test' },
+            fields,
+        )
+        expect(out.category_id).toBeNull()
+    })
+
+    it('nulls a nil-UUID reference value', () => {
+        const out = normalizeRefFieldsForSubmit({ brand_id: NIL }, fields)
+        expect(out.brand_id).toBeNull()
+    })
+
+    it('nulls a nil-UUID on ANY field, reference or not', () => {
+        const out = normalizeRefFieldsForSubmit({ some_id: NIL }, fields)
+        expect(out.some_id).toBeNull()
+    })
+
+    it('leaves a populated reference untouched', () => {
+        const id = '11111111-1111-1111-1111-111111111111'
+        const out = normalizeRefFieldsForSubmit({ category_id: id }, fields)
+        expect(out.category_id).toBe(id)
+    })
+
+    it('does NOT null an empty plain text field (empty string is legitimate)', () => {
+        const out = normalizeRefFieldsForSubmit(
+            { name: '', description: '' },
+            fields,
+        )
+        expect(out.name).toBe('')
+        expect(out.description).toBe('')
+    })
+
+    it('nulls empty search / dynamic_select references', () => {
+        const out = normalizeRefFieldsForSubmit(
+            { brand_id: '', owner_id: '' },
+            fields,
+        )
+        expect(out.brand_id).toBeNull()
+        expect(out.owner_id).toBeNull()
+    })
+
+    it('does not mutate the input object', () => {
+        const input = { category_id: '' }
+        normalizeRefFieldsForSubmit(input, fields)
+        expect(input.category_id).toBe('')
+    })
+})

package/src/action-modal-dispatcher.tsx

@@ -35,7 +35,8 @@ import {
 } from '@asteby/metacore-ui/primitives'
 import { Loader2 } from 'lucide-react'
 import { toast } from 'sonner'
-import { toastServerError, toastServerSuccess } from './server-error'
+import { toastServerError, toastServerSuccess, extractFieldErrors, localizeFieldIssue } from './server-error'
+import type { Translate } from './server-error'
 import { useApi } from './api-context'
 import { DynamicIcon } from './dynamic-icon'
 import { DynamicLineItems } from './dynamic-line-items'
@@ -403,6 +404,44 @@ function RecordPreview({ model, record }: { model: string; record: any }) {
     )
 }
 
+/** Humanize a field key for a label fallback ("unit_price" → "Unit Price"). */
+function humanizeKey(k: string): string {
+    return k.replace(/[._-]+/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
+}
+
+/** Localize a failed action submit's per-field `errors` (422 map or `{errors}`
+ *  body) into `{ [fieldKey]: localizedMessage }`, using each field's label.
+ *  Returns undefined when there is no usable per-field map. */
+function localizeActionFieldErrors(
+    err: unknown,
+    fields: readonly ActionFieldDef[] | undefined,
+    t: Translate,
+): Record<string, string> | undefined {
+    const map = extractFieldErrors(err)
+    if (!map) return undefined
+    const labelFor = (k: string) => {
+        const f = (fields ?? []).find(x => x.key === k)
+        return f?.label ? t(f.label, { defaultValue: f.label }) : humanizeKey(k)
+    }
+    const out: Record<string, string> = {}
+    for (const [k, issues] of Object.entries(map)) out[k] = localizeFieldIssue(issues[0], labelFor(k), t)
+    return out
+}
+
+/** Toast a failed action: a summary + localized per-field lines when the server
+ *  returned a per-field `errors` map, else the standard cause-carrying toast.
+ *  Used where inline rendering isn't wired (confirm / multi-step wizard). */
+function toastActionError(err: unknown, fields: readonly ActionFieldDef[] | undefined, t: Translate): void {
+    const localized = localizeActionFieldErrors(err, fields, t)
+    if (localized) {
+        toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }), {
+            description: Object.values(localized).join('\n'),
+        })
+        return
+    }
+    toastServerError(err, { t })
+}
+
 function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoint, onSuccess }: ActionModalProps) {
     const { t } = useTranslation()
     const api = useApi()
@@ -422,10 +461,10 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
                 onOpenChange(false)
                 onSuccess()
             } else {
-                toastServerError({ response: { data: res.data } }, { t })
+                toastActionError({ response: { data: res.data } }, action.fields, t)
             }
         } catch (err: any) {
-            toastServerError(err, { t })
+            toastActionError(err, action.fields, t)
         } finally {
             setExecuting(false)
         }
@@ -469,6 +508,8 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
     const api = useApi()
     const [formData, setFormData] = useState<Record<string, any>>({})
     const [executing, setExecuting] = useState(false)
+    // Per-field validation errors (localized), shown inline under each input.
+    const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({})
     // Related records to surface BELOW the form, as read-only context for the
     // record being acted on — e.g. the reception history of a transfer while
     // receiving against it. Sourced from the model's metadata.relations (the
@@ -512,29 +553,57 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
                 defaults[field.key] = field.defaultValue ?? (field.type === 'boolean' ? false : '')
             }
             setFormData(defaults)
+            setFieldErrors({})
         }
     }, [open, action.fields, record])
 
-    const updateField = (key: string, value: any) => setFormData((prev: Record<string, any>) => ({ ...prev, [key]: value }))
+    const updateField = (key: string, value: any) => {
+        setFormData((prev: Record<string, any>) => ({ ...prev, [key]: value }))
+        setFieldErrors(prev => {
+            if (!prev[key]) return prev
+            const next = { ...prev }
+            delete next[key]
+            return next
+        })
+    }
+
+    const handleActionError = (err: unknown) => {
+        const localized = localizeActionFieldErrors(err, action.fields, t)
+        if (localized) {
+            setFieldErrors(localized)
+            toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
+            return
+        }
+        toastServerError(err, { t })
+    }
 
     const execute = async () => {
         if (action.fields) {
+            // Client-side required check → mark ALL missing fields inline.
+            const missing: Record<string, string> = {}
             for (const field of action.fields) {
                 if (!field.required) continue
                 if (isLineItemsField(field)) {
                     const rows = formData[field.key]
                     if (!Array.isArray(rows) || rows.length === 0) {
-                        toast.error(`${tl(field.label)} requiere al menos un renglón`)
-                        return
+                        missing[field.key] = t('validation.line_items_required', {
+                            defaultValue: '{{label}} requiere al menos un renglón',
+                            label: tl(field.label),
+                        })
                     }
                     continue
                 }
                 if (!formData[field.key] && formData[field.key] !== false) {
-                    toast.error(`${tl(field.label)} es requerido`)
-                    return
+                    missing[field.key] = localizeFieldIssue({ code: 'required' }, tl(field.label), t)
                 }
             }
+            if (Object.keys(missing).length) {
+                setFieldErrors(missing)
+                toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
+                return
+            }
         }
+        setFieldErrors({})
         setExecuting(true)
         try {
             const url = buildActionUrl(endpoint, model, record.id, action.key)
@@ -544,10 +613,10 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
                 onOpenChange(false)
                 onSuccess()
             } else {
-                toastServerError({ response: { data: res.data } }, { t })
+                handleActionError({ response: { data: res.data } })
             }
         } catch (err: any) {
-            toastServerError(err, { t })
+            handleActionError(err)
         } finally {
             setExecuting(false)
         }
@@ -609,6 +678,9 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
                                         {tl(field.label)}
                                     </FieldLabel>
                                     {renderField(field, formData[field.key], (v: any) => updateField(field.key, v), formData)}
+                                    {fieldErrors[field.key] && (
+                                        <p className="text-destructive text-xs mt-1">{fieldErrors[field.key]}</p>
+                                    )}
                                 </FieldCell>
                             )
                         })}
@@ -749,10 +821,10 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
                 onOpenChange(false)
                 onSuccess()
             } else {
-                toastServerError({ response: { data: res.data } }, { t })
+                toastActionError({ response: { data: res.data } }, steps.flatMap(s => s.fields ?? []), t)
             }
         } catch (err: any) {
-            toastServerError(err, { t })
+            toastActionError(err, steps.flatMap(s => s.fields ?? []), t)
         } finally {
             setExecuting(false)
         }

package/src/dialogs/dynamic-record.tsx

@@ -48,12 +48,14 @@ import { format, parseISO } from 'date-fns'
 import { es } from 'date-fns/locale'
 import { ExternalLink, Loader2, CalendarIcon, ChevronDown, Check, Upload, X as XIcon } from 'lucide-react'
 import { useApi } from '../api-context'
+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'
 import { getFieldRef } from '../dynamic-form-schema'
 import { FieldCell } from '../field-grid'
 import { isNilUuid, normalizeNilUuid } from '../nil-uuid'
+import { normalizeRefFieldsForSubmit } from './normalize-submit'
 import { DynamicIcon, isLucideIconName } from '../dynamic-icon'
 import { humanizeToken } from '../dynamic-columns-helpers'
 import { formatDateCell } from '../dynamic-columns'
@@ -495,6 +497,10 @@ export function DynamicRecordDialog({
     const [relations, setRelations] = useState<RelationMeta[]>([])
     const [record, setRecord] = useState<any | null>(null)
     const [formValues, setFormValues] = useState<Record<string, any>>({})
+    // Per-field validation errors (localized strings), keyed by field.key. Shown
+    // inline under each input; populated from a 422 `errors` map or the client
+    // required-field check, cleared per-field on change and wholesale on reopen.
+    const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({})
     const [loading, setLoading] = useState(false)
     const [saving, setSaving] = useState(false)
     const [deleting, setDeleting] = useState(false)
@@ -509,6 +515,9 @@ export function DynamicRecordDialog({
         if (!open) return
         if (!isCreate && !recordId) return
 
+        // Fresh open → drop any validation errors from a prior submit.
+        setFieldErrors({})
+
         let cancelled = false
 
         // Seed instantly from the row the table already has so view/edit render
@@ -669,23 +678,63 @@ export function DynamicRecordDialog({
         onChange?.()
     }, [api, endpoint, model, recordId, isCreate, modalMeta, onChange])
 
+    // The human label for a field key, for localizing validation errors. Falls
+    // back to a humanized key when the field is unknown (e.g. a server-side key
+    // with no matching form field).
+    const labelForKey = (key: string): string => {
+        const f = (modalMeta?.fields ?? []).find(x => x.key === key)
+        if (f?.label) return f.label
+        return key.replace(/[._-]+/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
+    }
+
+    // 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 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, fallback: t('dynamic.save_error', { defaultValue: 'No se pudo guardar' }) })
+    }
+
     const handleSubmit = async (e?: React.FormEvent) => {
         e?.preventDefault()
         if (!modalMeta) return
 
         if (isEditable) {
+            // Collect ALL missing required fields (not just the first) and mark
+            // each inline instead of a single toast.
+            const missing: Record<string, string> = {}
             for (const field of modalMeta.fields ?? []) {
                 if (field.required && !formValues[field.key] && formValues[field.key] !== 0 && formValues[field.key] !== false) {
-                    toast.error(`El campo "${field.label}" es obligatorio`)
-                    return
+                    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
+            }
         }
 
+        // Required check passed → clear any prior validation errors.
+        setFieldErrors({})
+
+        // Empty reference pickers → null (not "" / nil-UUID) so nullable FK
+        // columns accept them instead of raising a 23503 FK violation.
+        const payload = normalizeRefFieldsForSubmit(formValues, modalMeta.fields)
+
         setSaving(true)
         try {
             if (isCreate && onCreate) {
-                const created = await onCreate(formValues)
+                const created = await onCreate(payload)
                 toast.success(modalMeta?.messages?.created || t('dynamic.create_success', { defaultValue: 'Registro creado correctamente' }))
                 onSaved?.(created ?? undefined)
                 onOpenChange(false)
@@ -693,7 +742,7 @@ export function DynamicRecordDialog({
             }
 
             if (!isCreate && recordId && onUpdate) {
-                const updated = await onUpdate(String(recordId), formValues)
+                const updated = await onUpdate(String(recordId), payload)
                 toast.success(modalMeta?.messages?.updated || t('dynamic.update_success', { defaultValue: 'Guardado correctamente' }))
                 onSaved?.(updated ?? undefined)
                 onOpenChange(false)
@@ -703,12 +752,12 @@ export function DynamicRecordDialog({
             let res
             if (isCreate) {
                 const createEndpoint = endpoint || `/dynamic/${model}`
-                res = await api.post(createEndpoint, formValues)
+                res = await api.post(createEndpoint, payload)
             } else {
                 const updateEndpoint = endpoint
                     ? `${endpoint}/${recordId}`
                     : `/dynamic/${model}/${recordId}`
-                res = await api.put(updateEndpoint, formValues)
+                res = await api.put(updateEndpoint, payload)
             }
 
             if (res.data?.success !== false) {
@@ -725,10 +774,13 @@ export function DynamicRecordDialog({
                 onSaved?.(res.data?.data ?? res.data ?? undefined)
                 onOpenChange(false)
             } else {
-                toast.error(res.data?.message || t('dynamic.save_error', { defaultValue: 'No se pudo guardar' }))
+                // Surface the server's real cause (`details`) as the toast
+                // description, not just the generic headline. `res.data` is the
+                // `{ success:false, message, details }` envelope.
+                handleSubmitError(res.data)
             }
         } catch (err: any) {
-            toast.error(err?.response?.data?.message || t('dynamic.save_error', { defaultValue: 'No se pudo guardar' }))
+            handleSubmitError(err)
         } finally {
             setSaving(false)
         }
@@ -742,7 +794,7 @@ export function DynamicRecordDialog({
             onOpenChange(false)
         } catch (err: any) {
             console.error('[DynamicRecordDialog] delete error:', err)
-            toast.error(err?.response?.data?.message || err?.message || t('dynamic.delete_error', { defaultValue: 'No se pudo eliminar el registro' }))
+            toastServerError(err, { t, fallback: t('dynamic.delete_error', { defaultValue: 'No se pudo eliminar el registro' }) })
         } finally {
             setDeleting(false)
         }
@@ -789,9 +841,17 @@ export function DynamicRecordDialog({
                                                 record={record}
                                                 value={formValues[field.key] ?? ''}
                                                 mode={mode}
-                                                onChange={val =>
+                                                error={fieldErrors[field.key]}
+                                                onChange={val => {
                                                     setFormValues((prev: Record<string, any>) => ({ ...prev, [field.key]: val }))
-                                                }
+                                                    // Clear this field's error as soon as the user edits it.
+                                                    setFieldErrors(prev => {
+                                                        if (!prev[field.key]) return prev
+                                                        const next = { ...prev }
+                                                        delete next[field.key]
+                                                        return next
+                                                    })
+                                                }}
                                             />
                                         </FieldCell>
                                     )
@@ -901,9 +961,11 @@ interface FieldRowProps {
     value: any
     mode: 'view' | 'edit' | 'create'
     onChange: (val: any) => void
+    /** Localized validation error for this field, shown in red under the input. */
+    error?: string
 }
 
-function FieldRow({ field, record, value, mode, onChange }: FieldRowProps) {
+function FieldRow({ field, record, value, mode, onChange, error }: FieldRowProps) {
     // A `readonly` field is server/system-generated (e.g. the GitHub addon's
     // `number`/`github_url`, filled by the API after the outbound create). On
     // CREATE it is excluded from the form entirely (see `visibleFields`); on EDIT
@@ -928,6 +990,10 @@ function FieldRow({ field, record, value, mode, onChange }: FieldRowProps) {
             ) : (
                 <EditField field={field} value={value} onChange={onChange} record={record} />
             )}
+
+            {error && mode !== 'view' && (
+                <p className="text-destructive text-xs mt-1">{error}</p>
+            )}
         </div>
     )
 }

package/src/dialogs/normalize-submit.ts

@@ -0,0 +1,49 @@
+// Pure submit-payload normalization for dynamic record forms. Kept in its own
+// module (no React / UI imports) so it is unit-testable in isolation and
+// reusable by any caller that builds a create/update payload.
+import { isNilUuid } from '../nil-uuid'
+import { getFieldRef } from '../dynamic-form-schema'
+import type { ActionFieldDef } from '../types'
+
+/** Minimal field-metadata shape the normalizer reads. Kept permissive so any
+ *  caller's field type (e.g. the dialog's `FieldDef[]`) is accepted. */
+type RefFieldMeta = Record<string, any>
+
+/**
+ * Normalize a submit payload so that EMPTY reference fields go to the server as
+ * `null` rather than as `""` or the nil UUID ("00000000-…"). A dynamic FK column
+ * (e.g. products.category_id, a nullable `ref`) rejects a non-null value that
+ * points at no row: sending `""`/nil-UUID triggers
+ *   insert ... violates foreign key constraint "fk_products_category" (23503)
+ * even though the user left the picker empty. This is generic — it keys off the
+ * field metadata (`getFieldRef` / dynamic_select / search), so every addon's
+ * optional relations benefit, not just products. Non-reference fields are left
+ * untouched (an empty text field is a legitimate `""`). Does not mutate `values`.
+ */
+export function normalizeRefFieldsForSubmit(
+    values: Record<string, any>,
+    fields: RefFieldMeta[] | undefined,
+): Record<string, any> {
+    const refKeys = new Set(
+        (fields ?? [])
+            .filter(
+                (f) =>
+                    !!getFieldRef(f as unknown as ActionFieldDef) ||
+                    f.type === 'dynamic_select' ||
+                    f.widget === 'dynamic_select' ||
+                    f.type === 'search',
+            )
+            .map((f) => f.key),
+    )
+    const out: Record<string, any> = { ...values }
+    for (const [k, v] of Object.entries(out)) {
+        // A nil UUID is never a real target row — null it out on any field.
+        if (isNilUuid(v)) {
+            out[k] = null
+            continue
+        }
+        // An empty reference picker means "no relation" → null (not "").
+        if (refKeys.has(k) && (v === '' || v == null)) out[k] = null
+    }
+    return out
+}