@asteby/metacore-runtime-react 32.0.0 → 32.1.0

package/src/__tests__/validator.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest'
+import { parseRuleString, checkValue, validateValues, bagHasErrors } from '../validator'
+import type { ActionFieldDef } from '../types'
+
+describe('parseRuleString', () => {
+    it('parses Laravel pipes', () => {
+        const s = parseRuleString('required|min:2|max:10|email')
+        expect(s.required).toBe(true)
+        expect(s.min).toBe(2)
+        expect(s.max).toBe(10)
+        expect(s.custom).toBe('email')
+    })
+    it('parses go-playground commas', () => {
+        const s = parseRuleString('required,min=2,max=100')
+        expect(s.required).toBe(true)
+        expect(s.min).toBe(2)
+        expect(s.max).toBe(100)
+    })
+    it('treats a slug as custom', () => {
+        expect(parseRuleString('$org.tax_id_validator').custom).toBe('$org.tax_id_validator')
+    })
+})
+
+describe('checkValue', () => {
+    it('required on empty', () => {
+        expect(checkValue('', { required: true })).toEqual([{ code: 'required' }])
+        expect(checkValue('x', { required: true })).toEqual([])
+    })
+    it('min/max length on strings', () => {
+        expect(checkValue('ab', { type: 'string', min: 3 })).toEqual([
+            { code: 'min', params: { min: 3, kind: 'length' } },
+        ])
+    })
+    it('regex + email', () => {
+        expect(checkValue('nope', { type: 'string', regex: '^[A-Z]+$' })[0]?.code).toBe('regex')
+        expect(checkValue('a@b.com', { custom: 'email' })).toEqual([])
+        expect(checkValue('not-an-email', { custom: 'email' })[0]?.code).toBe('email')
+    })
+    it('skips other rules when empty and not required', () => {
+        expect(checkValue('', { type: 'string', min: 3, custom: 'email' })).toEqual([])
+    })
+})
+
+describe('validateValues', () => {
+    const fields: ActionFieldDef[] = [
+        { key: 'name', label: 'Nombre', type: 'text', required: true },
+        { key: 'sku', label: 'SKU', type: 'text', validation: { min: 3, regex: '^[A-Z]+$' } },
+        {
+            key: 'items',
+            label: 'Renglones',
+            type: 'array',
+            required: true,
+            itemFields: [{ key: 'qty', label: 'Cantidad', type: 'number', required: true }],
+        },
+    ]
+    it('collects every field including dotted line-items', () => {
+        const bag = validateValues(fields, { sku: 'ab', items: [{ qty: '' }] })
+        expect(bag.name?.[0]?.code).toBe('required')
+        expect(bag.sku?.map(i => i.code).sort()).toEqual(['min', 'regex'])
+        expect(bag['items.0.qty']?.[0]?.code).toBe('required')
+        expect(bagHasErrors(bag)).toBe(true)
+    })
+    it('parses a laravel string on validation', () => {
+        const bag = validateValues(
+            [{ key: 'email', label: 'Email', type: 'text', validation: 'required|email' }],
+            { email: 'nope' },
+        )
+        expect(bag.email?.[0]?.code).toBe('email')
+    })
+})

package/src/action-modal-dispatcher.tsx

@@ -37,8 +37,10 @@ import {
 } from '@asteby/metacore-ui/primitives'
 import { Loader2 } from 'lucide-react'
 import { toast } from 'sonner'
-import { toastServerError, toastServerSuccess, extractFieldErrors, localizeFieldIssue } from './server-error'
+import { toastServerError, toastServerSuccess, extractFieldErrors, localizeFieldErrorMap } from './server-error'
 import type { Translate } from './server-error'
+import { validateValues, bagHasErrors } from './validator'
+import { validationCatalog } from './validation-catalog'
 import { useApi } from './api-context'
 import { DynamicIcon } from './dynamic-icon'
 import { DynamicLineItems } from './dynamic-line-items'
@@ -423,34 +425,38 @@ function localizeActionFieldErrors(
     err: unknown,
     fields: readonly ActionFieldDef[] | undefined,
     t: Translate,
+    language?: string,
 ): 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 labels: Record<string, string> = {}
+    for (const f of fields ?? []) {
+        labels[f.key] = f.label ? t(f.label, { defaultValue: f.label }) : humanizeKey(f.key)
     }
-    const out: Record<string, string> = {}
-    for (const [k, issues] of Object.entries(map)) out[k] = localizeFieldIssue(issues[0], labelFor(k), t)
-    return out
+    return localizeFieldErrorMap(map, t, { labels, language })
 }
 
 /** 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)
+function toastActionError(
+    err: unknown,
+    fields: readonly ActionFieldDef[] | undefined,
+    t: Translate,
+    language?: string,
+): void {
+    const localized = localizeActionFieldErrors(err, fields, t, language)
     if (localized) {
-        toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }), {
+        toast.error(t('validation.failed', { defaultValue: validationCatalog(language).failed }), {
             description: Object.values(localized).join('\n'),
         })
         return
     }
-    toastServerError(err, { t })
+    toastServerError(err, { t, language })
 }
 
 function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoint, onSuccess }: ActionModalProps) {
-    const { t } = useTranslation()
+    const { t, i18n } = useTranslation()
     const api = useApi()
     const [executing, setExecuting] = useState(false)
     // `action.label` is an addon-contributed i18n key; its locale bundle loads
@@ -468,10 +474,10 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
                 onOpenChange(false)
                 onSuccess()
             } else {
-                toastActionError({ response: { data: res.data } }, action.fields, t)
+                toastActionError({ response: { data: res.data } }, action.fields, t, i18n.language)
             }
         } catch (err: any) {
-            toastActionError(err, action.fields, t)
+            toastActionError(err, action.fields, t, i18n.language)
         } finally {
             setExecuting(false)
         }
@@ -507,7 +513,7 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
 }
 
 function GenericActionModal({ open, onOpenChange, action, model, record, endpoint, onSuccess }: ActionModalProps) {
-    const { t } = useTranslation()
+    const { t, i18n } = useTranslation()
     // Addon-contributed labels (action + fields) are i18n keys whose locale
     // bundle loads asynchronously; translate at render so they don't render raw.
     // defaultValue keeps an already-localized string unchanged.
@@ -574,39 +580,25 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
         })
     }
 
+    const lang = i18n.language
     const handleActionError = (err: unknown) => {
-        const localized = localizeActionFieldErrors(err, action.fields, t)
+        const localized = localizeActionFieldErrors(err, action.fields, t, lang)
         if (localized) {
             setFieldErrors(localized)
-            toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
+            toast.error(t('validation.failed', { defaultValue: validationCatalog(lang).failed }))
             return
         }
-        toastServerError(err, { t })
+        toastServerError(err, { t, language: lang })
     }
 
     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) {
-                        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) {
-                    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' }))
+            const bag = validateValues(action.fields, formData)
+            if (bagHasErrors(bag)) {
+                const labels: Record<string, string> = {}
+                for (const f of action.fields) labels[f.key] = tl(f.label)
+                setFieldErrors(localizeFieldErrorMap(bag, t, { labels, language: lang }))
+                toast.error(t('validation.failed', { defaultValue: validationCatalog(lang).failed }))
                 return
             }
         }
@@ -738,28 +730,17 @@ function buildFieldDefaults(fields: ActionFieldDef[], record: any): Record<strin
     return defaults
 }
 
-// validateFields returns the first validation error for a set of required
-// fields, or null when they all pass. Shared by the wizard (per-step gate) and
-// mirrors GenericActionModal's inline checks. `tl` localizes the field label.
-function validateFields(
+function wizardStepErrors(
     fields: ActionFieldDef[],
     formData: Record<string, any>,
-    tl: (s: string) => string,
-): string | null {
-    for (const field of fields) {
-        if (!field.required) continue
-        if (isLineItemsField(field)) {
-            const rows = formData[field.key]
-            if (!Array.isArray(rows) || rows.length === 0) {
-                return `${tl(field.label)} requiere al menos un renglón`
-            }
-            continue
-        }
-        if (!formData[field.key] && formData[field.key] !== false) {
-            return `${tl(field.label)} es requerido`
-        }
-    }
-    return null
+    t: Translate,
+    language?: string,
+): Record<string, string> | undefined {
+    const bag = validateValues(fields, formData)
+    if (!bagHasErrors(bag)) return undefined
+    const labels: Record<string, string> = {}
+    for (const f of fields) labels[f.key] = t(f.label, { defaultValue: f.label })
+    return localizeFieldErrorMap(bag, t, { labels, language })
 }
 
 // WizardActionModal — the third render-path: a multi-step form. It accumulates
@@ -770,7 +751,7 @@ function validateFields(
 // so line-items, dynamic_select, uploads and dates behave identically to a
 // single-page action form — no widget is duplicated.
 function WizardActionModal({ open, onOpenChange, action, model, record, endpoint, onSuccess }: ActionModalProps) {
-    const { t } = useTranslation()
+    const { t, i18n } = useTranslation()
     const tl = (s: string) => t(s, { defaultValue: s })
     const api = useApi()
     const steps = action.steps ?? []
@@ -801,9 +782,11 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
     const widthPx = hasLineItems ? '820px' : undefined
 
     const goNext = () => {
-        const err = validateFields(stepFields, formData, tl)
-        if (err) {
-            toast.error(err)
+        const localized = wizardStepErrors(stepFields, formData, t, i18n.language)
+        if (localized) {
+            toast.error(t('validation.failed', { defaultValue: validationCatalog(i18n.language).failed }), {
+                description: Object.values(localized).join('\n'),
+            })
             return
         }
         setStepIndex((i) => Math.min(i + 1, steps.length - 1))
@@ -815,9 +798,11 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
         // Guard every step's required fields on final submit (a user could reach
         // the last step with an untouched earlier line-items grid otherwise).
         for (const s of steps) {
-            const err = validateFields(s.fields ?? [], formData, tl)
-            if (err) {
-                toast.error(err)
+            const localized = wizardStepErrors(s.fields ?? [], formData, t, i18n.language)
+            if (localized) {
+                toast.error(t('validation.failed', { defaultValue: validationCatalog(i18n.language).failed }), {
+                    description: Object.values(localized).join('\n'),
+                })
                 return
             }
         }
@@ -830,10 +815,10 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
                 onOpenChange(false)
                 onSuccess()
             } else {
-                toastActionError({ response: { data: res.data } }, steps.flatMap(s => s.fields ?? []), t)
+                toastActionError({ response: { data: res.data } }, steps.flatMap(s => s.fields ?? []), t, i18n.language)
             }
         } catch (err: any) {
-            toastActionError(err, steps.flatMap(s => s.fields ?? []), t)
+            toastActionError(err, steps.flatMap(s => s.fields ?? []), t, i18n.language)
         } finally {
             setExecuting(false)
         }

package/src/dialogs/dynamic-record.tsx

@@ -53,7 +53,9 @@ 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, localizeFieldIssue } from '../server-error'
+import { toastServerError, extractFieldErrors, localizeFieldErrorMap } from '../server-error'
+import { validateValues, bagHasErrors } from '../validator'
+import { validationCatalog } from '../validation-catalog'
 import { DynamicSelectField, OptionLead, OptionThumb } from '../dynamic-select-field'
 import { DynamicRelations } from '../dynamic-relations'
 import { useOptionsResolver, type ResolvedOption } from '../use-options-resolver'
@@ -557,7 +559,7 @@ export function DynamicRecordDialog({
     onChange,
 }: DynamicRecordDialogProps) {
     const api = useApi()
-    const { t } = useTranslation()
+    const { t, i18n } = useTranslation()
     const [modalMeta, setModalMeta] = useState<ModalMetadata | null>(
         schema ? (schema as ModalMetadata) : null,
     )
@@ -758,25 +760,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 f.label
+        if (f?.label) return t(f.label, { defaultValue: 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 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' }))
+            const labels: Record<string, string> = {}
+            for (const f of modalMeta?.fields ?? []) labels[f.key] = labelForKey(f.key)
+            setFieldErrors(localizeFieldErrorMap(map, t, { labels, language: lang }))
+            toast.error(t('validation.failed', { defaultValue: validationCatalog(lang).failed }))
             return
         }
-        toastServerError(err, { t, fallback: t('dynamic.save_error', { defaultValue: 'No se pudo guardar' }) })
+        toastServerError(err, { t, language: lang, fallback: t('dynamic.save_error', { defaultValue: 'No se pudo guardar' }) })
     }
 
     const handleSubmit = async (e?: React.FormEvent) => {
@@ -789,15 +791,13 @@ 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 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' }))
+            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 })
+                setFieldErrors(localizeFieldErrorMap(bag, t, { labels, language: lang }))
+                toast.error(t('validation.failed', { defaultValue: validationCatalog(lang).failed }))
                 return
             }
         }
@@ -938,15 +938,12 @@ export function DynamicRecordDialog({
     // then advance. Mirrors handleSubmit's required check but scoped to the step.
     const goNextStep = () => {
         const step = groups[clampedStep]
-        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' }))
+        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 })
+            setFieldErrors(localizeFieldErrorMap(bag, t, { labels, language: lang }))
+            toast.error(t('validation.failed', { defaultValue: validationCatalog(lang).failed }))
             return
         }
         setFieldErrors({})

package/src/dynamic-form-schema.ts

@@ -2,7 +2,8 @@
 // callers (and unit tests) can use the zod schema without pulling in React or
 // metacore-ui primitives.
 import { z, type ZodTypeAny } from 'zod'
-import type { ActionFieldDef, FieldValidation, FieldOptionsConfig, OptionDef, VisibleWhen } from './types'
+import type { ActionFieldDef, FieldOptionsConfig, OptionDef, VisibleWhen } from './types'
+import { fieldValidationOf } from './validator'
 import { resolveValidatorToken } from './use-org-config-bridge'
 
 /**
@@ -164,7 +165,7 @@ function fieldToZod(field: ActionFieldDef): ZodTypeAny {
         return field.required ? arr.min(1, `${field.label} requiere al menos un renglón`) : arr
     }
 
-    const v = field.validation ?? ({} as FieldValidation)
+    const v = fieldValidationOf(field)
     const isNumeric = field.type === 'number'
     const isBool = field.type === 'boolean'
 

package/src/index.ts

@@ -22,11 +22,24 @@ export {
 export * from './options-context'
 export {
     extractServerError,
+    extractFieldErrors,
+    localizeFieldIssue,
+    localizeFieldErrorMap,
     toastServerError,
     toastServerSuccess,
     type ExtractedError,
     type Translate,
+    type FieldIssue,
 } from './server-error'
+export {
+    parseRuleString,
+    fieldValidationOf,
+    checkValue,
+    validateValues,
+    bagHasErrors,
+    type ValidationSpec,
+} from './validator'
+export { VALIDATION_CATALOGS, validationCatalog, validationMessageKey } from './validation-catalog'
 export * from './dynamic-table'
 export {
     DynamicKanban,

package/src/server-error.ts

@@ -10,6 +10,7 @@
 // or report it. This module keeps the headline but ALSO surfaces the cause as
 // the toast description, in ONE place so every call site behaves identically.
 import { toast } from 'sonner'
+import { validationCatalog, validationMessageKey } from './validation-catalog'
 
 /** Structured, display-ready view of an error: a headline + an optional cause. */
 export interface ExtractedError {
@@ -21,16 +22,29 @@ export interface ExtractedError {
     description?: string
 }
 
+function formatIssueEntry(v: unknown): string {
+    if (v == null) return ''
+    if (typeof v === 'string') return v
+    if (typeof v === 'object' && 'code' in (v as object)) {
+        const e = v as { code?: unknown; message?: unknown }
+        if (typeof e.message === 'string' && e.message.trim()) return e.message.trim()
+        if (typeof e.code === 'string' && e.code) return e.code
+    }
+    return String(v)
+}
+
 /** Flattens a validation `errors` payload (string | string[] | field→msgs map)
- *  into a single newline-joined string, or undefined when empty. */
+ *  into a single newline-joined string, or undefined when empty. Object entries
+ *  `{code, params}` render as the code (never `[object Object]`). */
 function joinErrors(errors: unknown): string | undefined {
     if (!errors) return undefined
     if (typeof errors === 'string') return errors || undefined
-    if (Array.isArray(errors)) return errors.filter(Boolean).map(String).join('\n') || undefined
+    if (Array.isArray(errors)) return errors.map(formatIssueEntry).filter(Boolean).join('\n') || undefined
     if (typeof errors === 'object') {
-        const parts = Object.entries(errors as Record<string, unknown>).map(
-            ([k, v]) => `${k}: ${Array.isArray(v) ? v.join(', ') : String(v)}`,
-        )
+        const parts = Object.entries(errors as Record<string, unknown>).map(([k, v]) => {
+            const body = Array.isArray(v) ? v.map(formatIssueEntry).filter(Boolean).join(', ') : formatIssueEntry(v)
+            return body ? `${k}: ${body}` : ''
+        }).filter(Boolean)
         return parts.join('\n') || undefined
     }
     return undefined
@@ -92,17 +106,12 @@ export interface FieldIssue {
     message?: string
 }
 
-/** 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: Record<string, string> = {
-    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',
+/** Spanish/English catalogs live in `validation-catalog.ts`. Hosts override any
+ *  key via i18next `validation.<code>`. `{{label}}` and code params (min/max/
+ *  allowed/ref/expected) interpolate through i18next. */
+function humanizeKey(k: string): string {
+    return k.replace(/[._-]+/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
 }
-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}`. */
@@ -147,16 +156,37 @@ export function extractFieldErrors(err: unknown): Record<string, FieldIssue[]> |
 }
 
 /**
- * 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.
+ * Localize a single `FieldIssue` to a human string using the field `label` and
+ * the operator's language. A pre-localized `message` passes through verbatim.
+ * Otherwise `code` is translated via `t('validation.'+key)` with a catalog
+ * default (es unless `language` is `en` / `en-*`).
  */
-export function localizeFieldIssue(issue: FieldIssue, label: string, t: Translate): string {
+export function localizeFieldIssue(
+    issue: FieldIssue,
+    label: string,
+    t: Translate,
+    language?: string,
+): string {
     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 ?? {}) })
+    const key = validationMessageKey(issue.code ?? '', issue.params)
+    const cat = validationCatalog(language)
+    const defaultValue = cat[key] ?? cat.fallback ?? '{{label}}: valor inválido'
+    return t(`validation.${key}`, { defaultValue, label, ...(issue.params ?? {}) })
+}
+
+/** Localize a whole 422 `errors` map into `{ [field]: firstMessage }` using
+ *  optional per-key labels (already translated) and the current language. */
+export function localizeFieldErrorMap(
+    map: Record<string, FieldIssue[]>,
+    t: Translate,
+    opts?: { labels?: Record<string, string>; language?: string },
+): Record<string, string> {
+    const out: Record<string, string> = {}
+    for (const [k, issues] of Object.entries(map)) {
+        const label = opts?.labels?.[k] ?? humanizeKey(k)
+        out[k] = localizeFieldIssue(issues[0]!, label, t, opts?.language)
+    }
+    return out
 }
 
 /** A dotted, space-free token (e.g. "pos.rate.created") — the shape of an i18n
@@ -192,15 +222,40 @@ export function toastServerSuccess(
 
 /**
  * Toast a server/network error, surfacing the REAL cause as the description
- * instead of a bare generic line. Pass the app's `t` so an i18n-key `message`
- * (e.g. "pos.error.no_rate") is localized; a plain-text message passes through
- * unchanged. Use everywhere a mutation/action can fail.
+ * instead of a bare generic line. A 422 `{errors:{field:[{code}]}}` bag is
+ * localized per-field (never `[object Object]` / English "validation failed").
+ * Pass `language` (i18n.language) so catalogs match the operator's lang;
+ * pass `labels` so field keys map to translated headers.
  */
-export function toastServerError(err: unknown, opts?: { t?: Translate; fallback?: string }): void {
+export function toastServerError(
+    err: unknown,
+    opts?: { t?: Translate; fallback?: string; language?: string; labels?: Record<string, string> },
+): void {
     const t = opts?.t
+    const lang = opts?.language
+    const cat = validationCatalog(lang)
+    const map = extractFieldErrors(err)
+    if (map) {
+        const localized = t
+            ? localizeFieldErrorMap(map, t, { labels: opts?.labels, language: lang })
+            : undefined
+        const title = t
+            ? t('validation.failed', { defaultValue: cat.failed })
+            : cat.failed
+        const description = localized
+            ? Object.values(localized).join('\n')
+            : Object.entries(map)
+                  .map(([k, issues]) => `${k}: ${issues[0]?.code ?? issues[0]?.message ?? ''}`)
+                  .join('\n')
+        toast.error(title, description ? { description } : undefined)
+        return
+    }
     const fallback =
         opts?.fallback ?? (t ? t('common.error', { defaultValue: 'Something went wrong' }) : 'Something went wrong')
-    const { title, description } = extractServerError(err, fallback)
-    const shownTitle = t ? t(title, { defaultValue: title }) : title
-    toast.error(shownTitle, description ? { description } : undefined)
+    const extracted = extractServerError(err, fallback)
+    let shownTitle = t ? t(extracted.title, { defaultValue: extracted.title }) : extracted.title
+    if (extracted.title === 'validation failed' || extracted.title === 'validation.failed') {
+        shownTitle = t ? t('validation.failed', { defaultValue: cat.failed }) : cat.failed
+    }
+    toast.error(shownTitle, extracted.description ? { description: extracted.description } : undefined)
 }

package/src/types.ts

@@ -317,11 +317,10 @@ export interface ColumnDefinition {
      */
     ref?: string
     /**
-     * Server-side validation rules the SDK can also pre-flight in the
-     * form layer. `custom` may be a literal slug or a $org.<key>
-     * reference resolved through the OrgConfigProvider.
+     * Write-time rules the SDK also pre-flights. Object form `{regex,min,max,custom}`
+     * or a Laravel / go-playground string (`required|min:2|email`).
      */
-    validation?: FieldValidation
+    validation?: FieldValidation | string
     /**
      * Declared schema for a jsonb line-items column (kernel v3 `item_fields`).
      * Each entry describes one sub-field of the array's row objects: a `key`
@@ -389,13 +388,11 @@ export interface VisibleWhen {
     in?: string[]
 }
 
-// Mirrors `ValidationRule` from packages/sdk/src/generated/manifest.ts. Kept
-// inline here so runtime-react does not import generated kernel types directly
-// — apps and addons author ActionFieldDef literals.
-//
-// `custom` accepts either a literal validator slug (e.g. `mx.rfc`) registered
-// via `registerValidator`, or a `$org.<key>` reference resolved through the
-// OrgConfigProvider — same contract as kernel ColumnDef.Validation.Custom.
+// Write-time + client-side constraints. The kernel enforces these on
+// create/update and action payloads (locale-agnostic codes); the SDK
+// pre-flights the same rules and localizes `validation.<code>` to the
+// operator's language. `custom` is a slug (`email`, `rfc.tax_id`) or a
+// `$org.<key>` reference resolved through OrgConfigProvider.
 export interface FieldValidation {
     regex?: string
     min?: number
@@ -469,7 +466,7 @@ export interface ActionFieldDef {
     defaultValue?: any
     placeholder?: string
     searchEndpoint?: string
-    validation?: FieldValidation
+    validation?: FieldValidation | string
     widget?: FieldWidget | string
     /**
      * FK target model — same semantics as ColumnDefinition.ref. When