@asteby/metacore-runtime-react 25.1.3 → 25.1.5

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @asteby/metacore-runtime-react
 
+## 25.1.5
+
+### Patch Changes
+
+- 6f20bf5: normalize-submit: prefer the explicit `nullable` field flag served by the kernel (v0.77.1+) when deciding to null an empty reference, falling back to the type-based heuristic for older hosts that don't serve the flag.
+
+## 25.1.4
+
+### Patch Changes
+
+- bdbc542: Per-field validation error rendering + Spanish localization. On a 422 with a
+  `{ errors: { <field>: [{ code, params }] } }` map, create/edit dialogs and action
+  modals now show each field's first error inline (in red under the input) plus a
+  summary toast, instead of one flattened toast. Errors localize to Spanish from
+  locale-agnostic codes (`required`, `invalid_option`, `not_found`, `duplicate`,
+  `invalid_type`, generic fallback) using the field label via i18next `{{label}}`
+  interpolation, so hosts can override the copy under `validation.<code>`.
+  Pre-localized string entries pass through verbatim. Adds exported helpers
+  `extractFieldErrors` and `localizeFieldIssue` (with the `FieldIssue` type) in
+  `server-error`. The client-side required check now marks all missing fields
+  inline rather than toasting only the first.
+
 ## 25.1.3
 
 ### Patch Changes

package/dist/action-modal-dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-modal-dispatcher.d.ts","sourceRoot":"","sources":["../src/action-modal-dispatcher.tsx"],"names":[],"mappings":"AAyDA,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAExB,MAAM,sBAAsB,CAAA;AAE7B,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;AA0FhD,wBAAgB,qBAAqB,CAAC,EAClC,IAAI,EACJ,YAAY,EACZ,MAAM,EACN,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,GACZ,EAAE,gBAAgB,sCA+DlB"}
+{"version":3,"file":"action-modal-dispatcher.d.ts","sourceRoot":"","sources":["../src/action-modal-dispatcher.tsx"],"names":[],"mappings":"AA0DA,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAExB,MAAM,sBAAsB,CAAA;AAE7B,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;AA0FhD,wBAAgB,qBAAqB,CAAC,EAClC,IAAI,EACJ,YAAY,EACZ,MAAM,EACN,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,GACZ,EAAE,gBAAgB,sCA+DlB"}

package/dist/action-modal-dispatcher.js

@@ -12,7 +12,7 @@ import { useTranslation } from 'react-i18next';
 import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, Button, Input, Textarea, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, Switch, } 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 { useApi } from './api-context';
 import { DynamicIcon } from './dynamic-icon';
 import { DynamicLineItems } from './dynamic-line-items';
@@ -250,6 +250,39 @@ function RecordPreview({ model, record }) {
             return (_jsxs("div", { className: "flex items-baseline gap-3 border-t px-3 py-1.5 first:border-t-0", children: [_jsx("span", { className: "w-1/3 shrink-0 truncate text-muted-foreground", children: label }), _jsx("div", { className: "min-w-0 flex-1 [&_p]:py-0", children: _jsx(ViewValue, { field: col, value: value, record: record }) })] }, col.key));
         }) }));
 }
+/** Humanize a field key for a label fallback ("unit_price" → "Unit Price"). */
+function humanizeKey(k) {
+    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, fields, t) {
+    const map = extractFieldErrors(err);
+    if (!map)
+        return undefined;
+    const labelFor = (k) => {
+        const f = (fields ?? []).find(x => x.key === k);
+        return f?.label ? t(f.label, { defaultValue: f.label }) : humanizeKey(k);
+    };
+    const out = {};
+    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, fields, t) {
+    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 }) {
     const { t } = useTranslation();
     const api = useApi();
@@ -269,11 +302,11 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
                 onSuccess();
             }
             else {
-                toastServerError({ response: { data: res.data } }, { t });
+                toastActionError({ response: { data: res.data } }, action.fields, t);
             }
         }
         catch (err) {
-            toastServerError(err, { t });
+            toastActionError(err, action.fields, t);
         }
         finally {
             setExecuting(false);
@@ -290,6 +323,8 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
     const api = useApi();
     const [formData, setFormData] = useState({});
     const [executing, setExecuting] = useState(false);
+    // Per-field validation errors (localized), shown inline under each input.
+    const [fieldErrors, setFieldErrors] = useState({});
     // 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
@@ -334,28 +369,56 @@ 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, value) => setFormData((prev) => ({ ...prev, [key]: value }));
+    const updateField = (key, value) => {
+        setFormData((prev) => ({ ...prev, [key]: value }));
+        setFieldErrors(prev => {
+            if (!prev[key])
+                return prev;
+            const next = { ...prev };
+            delete next[key];
+            return next;
+        });
+    };
+    const handleActionError = (err) => {
+        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 = {};
             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);
@@ -366,11 +429,11 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
                 onSuccess();
             }
             else {
-                toastServerError({ response: { data: res.data } }, { t });
+                handleActionError({ response: { data: res.data } });
             }
         }
         catch (err) {
-            toastServerError(err, { t });
+            handleActionError(err);
         }
         finally {
             setExecuting(false);
@@ -394,7 +457,7 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
                                 const fullWidth = isLineItemsField(field) ||
                                     resolveWidget(field) === 'textarea' ||
                                     resolveWidget(field) === 'richtext';
-                                return (_jsxs(FieldCell, { fullWidth: fullWidth, children: [_jsx(FieldLabel, { htmlFor: field.key, required: field.required, children: tl(field.label) }), renderField(field, formData[field.key], (v) => updateField(field.key, v), formData)] }, field.key));
+                                return (_jsxs(FieldCell, { fullWidth: fullWidth, children: [_jsx(FieldLabel, { htmlFor: field.key, required: field.required, children: tl(field.label) }), renderField(field, formData[field.key], (v) => updateField(field.key, v), formData), fieldErrors[field.key] && (_jsx("p", { className: "text-destructive text-xs mt-1", children: fieldErrors[field.key] }))] }, field.key));
                             }), relations.length > 0 && (_jsx(FieldCell, { fullWidth: true, children: _jsx(DynamicRelations, { record: record, relations: relations }) }))] }) }), _jsxs(DialogFooter, { className: "shrink-0", children: [_jsx(Button, { variant: "outline", onClick: () => onOpenChange(false), disabled: executing, children: t('common.cancel') }), _jsxs(Button, { onClick: execute, disabled: executing, style: action.color ? { backgroundColor: action.color, color: 'white' } : undefined, children: [executing ? _jsx(Loader2, { className: "mr-2 h-4 w-4 animate-spin" }) : _jsx(DynamicIcon, { name: action.icon, className: "mr-2 h-4 w-4" }), tl(action.label)] })] })] }) }));
 }
 // buildFieldDefaults seeds formData for a set of action fields, honoring the
@@ -495,11 +558,11 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
                 onSuccess();
             }
             else {
-                toastServerError({ response: { data: res.data } }, { t });
+                toastActionError({ response: { data: res.data } }, steps.flatMap(s => s.fields ?? []), t);
             }
         }
         catch (err) {
-            toastServerError(err, { t });
+            toastActionError(err, steps.flatMap(s => s.fields ?? []), t);
         }
         finally {
             setExecuting(false);

package/dist/dialogs/dynamic-record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-record.d.ts","sourceRoot":"","sources":["../../src/dialogs/dynamic-record.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"dynamic-record.d.ts","sourceRoot":"","sources":["../../src/dialogs/dynamic-record.tsx"],"names":[],"mappings":"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"}

package/dist/dialogs/dynamic-record.js

@@ -19,7 +19,7 @@ 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 } from '../server-error';
+import { toastServerError, extractFieldErrors, localizeFieldIssue } from '../server-error';
 import { DynamicSelectField, OptionLead, OptionThumb } from '../dynamic-select-field';
 import { DynamicRelations } from '../dynamic-relations';
 import { useOptionsResolver } from '../use-options-resolver';
@@ -254,6 +254,10 @@ export function DynamicRecordDialog({ open, onOpenChange, mode, model, recordId,
     const [relations, setRelations] = useState([]);
     const [record, setRecord] = useState(null);
     const [formValues, setFormValues] = useState({});
+    // 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({});
     const [loading, setLoading] = useState(false);
     const [saving, setSaving] = useState(false);
     const [deleting, setDeleting] = useState(false);
@@ -267,6 +271,8 @@ export function DynamicRecordDialog({ open, onOpenChange, mode, model, recordId,
             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
         // without a spinner. The list row carries the pro siblings (resolved
@@ -424,18 +430,52 @@ export function DynamicRecordDialog({ open, onOpenChange, mode, model, recordId,
         }
         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) => {
+        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) => {
+        const map = extractFieldErrors(err);
+        if (map) {
+            const next = {};
+            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) => {
         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 = {};
             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);
@@ -482,11 +522,11 @@ export function DynamicRecordDialog({ open, onOpenChange, mode, model, recordId,
                 // 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.
-                toastServerError(res.data, { t, fallback: t('dynamic.save_error', { defaultValue: 'No se pudo guardar' }) });
+                handleSubmitError(res.data);
             }
         }
         catch (err) {
-            toastServerError(err, { t, fallback: t('dynamic.save_error', { defaultValue: 'No se pudo guardar' }) });
+            handleSubmitError(err);
         }
         finally {
             setSaving(false);
@@ -514,13 +554,23 @@ export function DynamicRecordDialog({ open, onOpenChange, mode, model, recordId,
                                                     const isFullWidth = field.type === 'textarea' ||
                                                         field.widget === 'textarea' ||
                                                         field.widget === 'richtext';
-                                                    return (_jsx(FieldCell, { fullWidth: isFullWidth, children: _jsx(FieldRow, { field: field, record: record, value: formValues[field.key] ?? '', mode: mode, onChange: val => setFormValues((prev) => ({ ...prev, [field.key]: val })) }) }, field.key));
+                                                    return (_jsx(FieldCell, { fullWidth: isFullWidth, children: _jsx(FieldRow, { field: field, record: record, value: formValues[field.key] ?? '', mode: mode, error: fieldErrors[field.key], onChange: val => {
+                                                                setFormValues((prev) => ({ ...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;
+                                                                });
+                                                            } }) }, field.key));
                                                 }), record?.external_url && (_jsx("div", { className: "sm:col-span-2 min-w-0", children: _jsxs("a", { href: record.external_url, target: "_blank", rel: "noreferrer", className: "inline-flex items-center gap-1.5 text-sm text-primary hover:underline mt-1", children: [_jsx(ExternalLink, { className: "h-3.5 w-3.5" }), "Ver en ", record.external_provider ?? 'proveedor externo'] }) }))] }), !isCreate && record && relations.length > 0 && (_jsx("div", { className: "mt-6", children: _jsx(DynamicRelations, { record: record, relations: relations, canCreate: mode === 'edit', canEdit: mode === 'edit', canDelete: mode === 'edit', onChange: handleChildChange }) }))] }) }) }) })) : null }), _jsxs(DialogFooter, { className: "p-4 border-t shrink-0 sm:justify-between", children: [isView && onOpenFullPage ? (_jsxs(Button, { variant: "ghost", size: "sm", className: "text-muted-foreground", onClick: () => { onOpenChange(false); onOpenFullPage(); }, children: [_jsx(ExternalLink, { className: "mr-1.5 h-3.5 w-3.5" }), "Ver p\u00E1gina completa"] })) : _jsx("span", {}), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", onClick: () => onOpenChange(false), disabled: saving || deleting, children: config.cancelLabel }), isView && onDelete && (_jsxs(Button, { variant: "destructive", onClick: handleDelete, disabled: deleting || loading, children: [deleting && _jsx(Loader2, { className: "mr-2 h-4 w-4 animate-spin" }), deleting ? 'Eliminando...' : 'Eliminar'] })), isView && onEdit && (_jsx(Button, { onClick: onEdit, disabled: deleting || loading, children: "Editar" })), isEditable && (_jsxs(Button, { type: "submit", form: "dynamic-record-form", disabled: saving || loading, children: [saving && _jsx(Loader2, { className: "mr-2 h-4 w-4 animate-spin" }), saving ? config.submittingLabel : config.submitLabel] }))] })] })] }) }));
 }
 function LoadingSkeleton() {
     return (_jsx("div", { className: "grid grid-cols-1 sm:grid-cols-2 gap-x-6 gap-y-4", children: Array.from({ length: 6 }).map((_, i) => (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(Skeleton, { className: "h-3.5 w-24" }), _jsx(Skeleton, { className: "h-9 w-full" })] }, i))) }));
 }
-function FieldRow({ field, record, value, mode, onChange }) {
+function FieldRow({ field, record, value, mode, onChange, error }) {
     // 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
@@ -528,7 +578,7 @@ function FieldRow({ field, record, value, mode, onChange }) {
     // so the user sees its value without being able to change it. View mode keeps
     // the rich read-only renderer.
     const isEditReadonly = mode === 'edit' && !!field.readonly;
-    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsxs(Label, { className: "text-xs font-medium text-muted-foreground uppercase tracking-wide", children: [field.label, field.required && mode !== 'view' && !isEditReadonly && (_jsx("span", { className: "text-destructive ml-0.5", children: "*" }))] }), mode === 'view' ? (_jsx(ViewValue, { field: field, value: value, record: record })) : isEditReadonly ? (_jsx(ReadonlyEditField, { field: field, value: value })) : (_jsx(EditField, { field: field, value: value, onChange: onChange, record: record }))] }));
+    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsxs(Label, { className: "text-xs font-medium text-muted-foreground uppercase tracking-wide", children: [field.label, field.required && mode !== 'view' && !isEditReadonly && (_jsx("span", { className: "text-destructive ml-0.5", children: "*" }))] }), mode === 'view' ? (_jsx(ViewValue, { field: field, value: value, record: record })) : isEditReadonly ? (_jsx(ReadonlyEditField, { field: field, value: value })) : (_jsx(EditField, { field: field, value: value, onChange: onChange, record: record })), error && mode !== 'view' && (_jsx("p", { className: "text-destructive text-xs mt-1", children: error }))] }));
 }
 // ReadonlyEditField — the edit-mode rendering of a `readonly` (system-generated)
 // field: a disabled, muted input that shows the current value without allowing

package/dist/dialogs/normalize-submit.d.ts

@@ -7,10 +7,23 @@ type RefFieldMeta = Record<string, any>;
  * (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`.
+ * even though the user left the picker empty.
+ *
+ * Nullability decision (Fase 4): prefer the EXPLICIT `nullable` flag the kernel
+ * (v0.77.1+) now serves per field (`modelbase.FieldDef.Nullable`, `!Required`).
+ * When `field.nullable === true` an empty value is submitted as `null`; when
+ * `field.nullable === false` the value is respected. When the flag is absent
+ * (undefined — older hosts that don't serve it yet) we fall back to the legacy
+ * type-based heuristic (`getFieldRef` / dynamic_select / search). This keeps
+ * backward-compat while letting the contract, not a guess, drive the decision.
+ *
+ * The explicit flag also lets us null an empty OPTIONAL ref whose column is NOT
+ * a uuid (which the uuid-only heuristic never covered). To avoid nulling a plain
+ * optional text field — where `""` is a legitimate value, not "no relation" — we
+ * gate the explicit path on the field ALSO looking like a reference/relation
+ * (`getFieldRef` / dynamic_select / search). A nullable non-ref scalar keeps its
+ * `""`. This is generic — every addon's optional relations benefit. Does not
+ * mutate `values`.
  */
 export declare function normalizeRefFieldsForSubmit(values: Record<string, any>, fields: RefFieldMeta[] | undefined): Record<string, any>;
 export {};

package/dist/dialogs/normalize-submit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-submit.d.ts","sourceRoot":"","sources":["../../src/dialogs/normalize-submit.ts"],"names":[],"mappings":"AAOA;wEACwE;AACxE,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAEvC;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,YAAY,EAAE,GAAG,SAAS,GACnC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAuBrB"}
+{"version":3,"file":"normalize-submit.d.ts","sourceRoot":"","sources":["../../src/dialogs/normalize-submit.ts"],"names":[],"mappings":"AAOA;wEACwE;AACxE,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,2BAA2B,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,YAAY,EAAE,GAAG,SAAS,GACnC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAuCrB"}

package/dist/dialogs/normalize-submit.js

@@ -9,18 +9,35 @@ import { getFieldRef } from '../dynamic-form-schema';
  * (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`.
+ * even though the user left the picker empty.
+ *
+ * Nullability decision (Fase 4): prefer the EXPLICIT `nullable` flag the kernel
+ * (v0.77.1+) now serves per field (`modelbase.FieldDef.Nullable`, `!Required`).
+ * When `field.nullable === true` an empty value is submitted as `null`; when
+ * `field.nullable === false` the value is respected. When the flag is absent
+ * (undefined — older hosts that don't serve it yet) we fall back to the legacy
+ * type-based heuristic (`getFieldRef` / dynamic_select / search). This keeps
+ * backward-compat while letting the contract, not a guess, drive the decision.
+ *
+ * The explicit flag also lets us null an empty OPTIONAL ref whose column is NOT
+ * a uuid (which the uuid-only heuristic never covered). To avoid nulling a plain
+ * optional text field — where `""` is a legitimate value, not "no relation" — we
+ * gate the explicit path on the field ALSO looking like a reference/relation
+ * (`getFieldRef` / dynamic_select / search). A nullable non-ref scalar keeps its
+ * `""`. This is generic — every addon's optional relations benefit. Does not
+ * mutate `values`.
  */
 export function normalizeRefFieldsForSubmit(values, fields) {
-    const refKeys = new Set((fields ?? [])
-        .filter((f) => !!getFieldRef(f) ||
+    const isRefField = (f) => !!getFieldRef(f) ||
         f.type === 'dynamic_select' ||
         f.widget === 'dynamic_select' ||
-        f.type === 'search')
-        .map((f) => f.key));
+        f.type === 'search';
+    // Index fields by key so we can consult the explicit `nullable` flag.
+    const fieldByKey = new Map();
+    for (const f of fields ?? []) {
+        if (f && typeof f.key === 'string')
+            fieldByKey.set(f.key, f);
+    }
     const out = { ...values };
     for (const [k, v] of Object.entries(out)) {
         // A nil UUID is never a real target row — null it out on any field.
@@ -28,8 +45,24 @@ export function normalizeRefFieldsForSubmit(values, fields) {
             out[k] = null;
             continue;
         }
-        // An empty reference picker means "no relation" → null (not "").
-        if (refKeys.has(k) && (v === '' || v == null))
+        const isEmpty = v === '' || v == null;
+        if (!isEmpty)
+            continue;
+        const f = fieldByKey.get(k);
+        const nullable = f?.nullable;
+        if (nullable === true) {
+            // Explicit contract flag wins. Only null a reference/relation so a
+            // legitimately-empty optional plain-text field keeps its `""`.
+            if (f && isRefField(f))
+                out[k] = null;
+            continue;
+        }
+        if (nullable === false) {
+            // Explicitly non-nullable → respect the empty value as-is.
+            continue;
+        }
+        // No explicit flag (older host): fall back to the type-based heuristic.
+        if (f && isRefField(f))
             out[k] = null;
     }
     return out;

package/dist/server-error.d.ts

@@ -18,10 +18,35 @@ export interface ExtractedError {
  *   description ← data.details → data.error → joined data.errors → raw err.message
  */
 export declare function extractServerError(err: unknown, fallbackTitle: string): ExtractedError;
-/** i18n translator, tolerant of non-keys (returns `defaultValue`/the input). */
+/** i18n translator, tolerant of non-keys (returns `defaultValue`/the input).
+ *  Accepts arbitrary interpolation values (e.g. `label`, plus a code's `params`)
+ *  so `localizeFieldIssue` can pass `{{label}}` and friends through i18next. */
 export type Translate = (key: string, opts?: {
     defaultValue?: string;
+    [k: string]: unknown;
 }) => string;
+/** A single normalized validation issue for one field: either a machine `code`
+ *  (+ optional `params`) to localize, or a ready-to-show `message` string. */
+export interface FieldIssue {
+    code?: string;
+    params?: Record<string, any>;
+    message?: string;
+}
+/**
+ * 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 declare function extractFieldErrors(err: unknown): Record<string, FieldIssue[]> | 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 declare function localizeFieldIssue(issue: FieldIssue, label: string, t: Translate): string;
 /**
  * Toast a successful mutation/action response, LOCALIZED. The kernel/host often
  * returns a hardcoded English `message` ("Record created successfully"); echoing

package/dist/server-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-error.d.ts","sourceRoot":"","sources":["../src/server-error.ts"],"names":[],"mappings":"AAaA,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;IACb;;gDAE4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAuBtF;AAED,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,MAAM,CAAA;AAUjF;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;IAAE,CAAC,CAAC,EAAE,SAAS,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,IAAI,CAUN;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;IAAE,CAAC,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAOhG"}
+{"version":3,"file":"server-error.d.ts","sourceRoot":"","sources":["../src/server-error.ts"],"names":[],"mappings":"AAaA,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC3B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;IACb;;gDAE4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAuBtF;AAED;;gFAEgF;AAChF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,KAAK,MAAM,CAAA;AAUvG;8EAC8E;AAC9E,MAAM,WAAW,UAAU;IACvB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAkCD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,GAAG,SAAS,CAazF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAKzF;AAUD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;IAAE,CAAC,CAAC,EAAE,SAAS,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,IAAI,CAUN;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;IAAE,CAAC,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAOhG"}

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/dist/types.d.ts

@@ -324,6 +324,14 @@ export interface ActionFieldDef {
     label: string;
     type: string;
     required?: boolean;
+    /**
+     * Explicit nullability flag served by the kernel (v0.77.1+) from
+     * `modelbase.FieldDef.Nullable` (populated as `!Required`). An optional `ref`
+     * arrives as `nullable: true`. When present it authoritatively decides whether
+     * an empty value should be submitted as `null`; when absent (older hosts) the
+     * SDK falls back to type-based heuristics. Additive / optional.
+     */
+    nullable?: boolean;
     options?: OptionDef[];
     defaultValue?: any;
     placeholder?: string;