@asteby/metacore-runtime-react 31.1.1 → 32.1.0

package/src/addon-loader.tsx

@@ -3,17 +3,26 @@
 // `remoteEntry.js` as an ESM container, loads the exposed `./register` module,
 // and calls `register(api)` with the AddonAPI injected by the host.
 //
-// Why @module-federation/runtime (not the old manual init/get machinery):
-// the host's Vite build uses `@module-federation/vite`'s `federation()` plugin,
-// which auto-initialises the shared scope at host boot. `registerRemotes` +
-// `loadRemote` then transparently wire the remote into that already-initialised
-// share scope — so the remote consumes the HOST's React/SDK singletons instead
-// of bundling its own. That's the whole point: it fixes the `useState`-null
-// crash WITHOUT this loader ever touching a share scope manually.
+// Fiber lifecycle (Cordis-style): when `url` (the `?v=` cache-bust) changes,
+// the previous plugin.dispose / returned Disposable run, the host registry
+// unbinds that addonKey, the SW addon-federation cache for that key is
+// purged, and register() runs again against the new remote. The host shell
+// (auth, QueryClient, WebSocket, service worker controller) is not touched.
 import { useEffect, useRef, useState } from 'react'
 import { registerRemotes, loadRemote } from '@module-federation/runtime'
-import type { AddonAPI, AddonLayout } from '@asteby/metacore-sdk'
+import type { AddonAPI, AddonLayout, Registry } from '@asteby/metacore-sdk'
 import { useDeclareAddonLayout } from './addon-layout-context'
+import {
+    composeDisposables,
+    disposableFromRegisterResult,
+    markRemoteRegistered,
+    purgeAddonFrontendCache,
+    resolvePluginExports,
+    runDispose,
+    shouldReregisterRemote,
+    type AddonRegisterModule,
+    type Disposable,
+} from './addon-fiber'
 
 export interface AddonLoaderProps {
     /** Unique key of the addon — maps to the federation container name. */
@@ -24,9 +33,25 @@ export interface AddonLoaderProps {
     module?: string
     /** Host-provided API passed to the addon's register() call. */
     api: AddonAPI
+    /**
+     * Host registry used to {@link Registry.unbind} this addon's contributions
+     * on dispose. Optional so legacy hosts keep compiling; without it, fiber
+     * remounts leak routes/actions.
+     */
+    hostRegistry?: Registry
+    /**
+     * Addon key for SW cache purge. Defaults to `api.manifest.key`.
+     */
+    addonKey?: string
+    /**
+     * Registry owner passed to {@link Registry.unbind}. Defaults to `addonKey`.
+     * Immersive `./plugin` fibers use `${key}::view` so they don't wipe the
+     * shell `./register` contributions of the same addon.
+     */
+    unbindKey?: string
     /** Optional rendering while loading. */
     fallback?: React.ReactNode
-    /** Called once the addon has successfully registered. */
+    /** Called once the addon has successfully registered (including re-register). */
     onReady?: () => void
     /** Called if loading fails. */
     onError?: (err: Error) => void
@@ -45,17 +70,6 @@ export interface AddonLoaderProps {
     children?: React.ReactNode
 }
 
-/** Shape of the exposed `./register` module. */
-interface AddonRegisterModule {
-    register?: (api: AddonAPI) => void | Promise<void>
-    default?: (api: AddonAPI) => void | Promise<void>
-}
-
-// `registerRemotes` is additive + idempotent across re-mounts; we still track
-// which scopes we've registered to avoid redundant `force` churn (each `force`
-// re-register wipes that remote's module cache and logs a runtime warning).
-const registered = new Set<string>()
-
 // Derive the `loadRemote` id from the scope + exposed module name. MF resolves
 // `"<remoteName>/<expose>"` — e.g. `metacore_tickets/register` for the
 // `"./register"` expose. We strip the leading `./` of the expose path.
@@ -100,28 +114,15 @@ async function loadAddon(
     url: string,
     module: string,
 ): Promise<AddonRegisterModule | null> {
-    // Register the remote container as an ES module. `type: 'module'` matches
-    // the `@module-federation/vite` remote (remoteEntry.js is an ESM bundle).
-    // The `url` already carries the `?v=` cache-bust the host computed, so the
-    // browser refetches a fresh remoteEntry when the addon version changes.
-    //
-    // Both calls are wrapped in `withRuntimeReady` because EITHER can throw
-    // RUNTIME-009 when an addon mounts ahead of the host's federation init —
-    // registration is what actually touches the (maybe-uninitialised) runtime.
-    if (!registered.has(scope)) {
+    // Re-register whenever the `?v=` URL changes so a fiber swap actually
+    // fetches the new remoteEntry. `force: true` wipes that remote's module
+    // cache — without it, loadRemote would keep serving the previous bundle.
+    if (shouldReregisterRemote(scope, url)) {
         await withRuntimeReady(() =>
-            registerRemotes(
-                [{ name: scope, entry: url, type: 'module' }],
-                // `force: true` so a re-registration with a new `?v=` URL (addon
-                // hot-swap / version bump) overwrites the stale entry + cache.
-                { force: true },
-            ),
+            registerRemotes([{ name: scope, entry: url, type: 'module' }], { force: true }),
         )
-        registered.add(scope)
+        markRemoteRegistered(scope, url)
     }
-    // loadRemote("<scope>/<expose>") returns the exposed module namespace (or
-    // null if it can't be resolved). No manual share-scope init — the host's
-    // federation runtime already initialised it.
     return withRuntimeReady(() =>
         loadRemote<AddonRegisterModule>(remoteId(scope, module)),
     )
@@ -132,6 +133,9 @@ export function AddonLoader({
     url,
     module = './register',
     api,
+    hostRegistry,
+    addonKey,
+    unbindKey,
     fallback = null,
     onReady,
     onError,
@@ -140,7 +144,7 @@ export function AddonLoader({
 }: AddonLoaderProps) {
     const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading')
     const [error, setError] = useState<Error | null>(null)
-    const didRegister = useRef(false)
+    const disposeRef = useRef<Disposable | undefined>(undefined)
 
     // Propagate the addon's preferred layout to the host shell via context.
     // No-op when `layout` is undefined or `"shell"` (legacy default). Cleanup
@@ -150,20 +154,28 @@ export function AddonLoader({
 
     useEffect(() => {
         let cancelled = false
+        const key = addonKey || api.manifest?.key
+        const owner = unbindKey || key
         ;(async () => {
             try {
+                setStatus('loading')
+                if (key) await purgeAddonFrontendCache(key)
                 const mod = await loadAddon(scope, url, module)
                 if (cancelled) return
-                const register = mod?.register ?? mod?.default
-                if (typeof register !== 'function') {
+                const plugin = resolvePluginExports(mod)
+                if (typeof plugin.register !== 'function') {
                     throw new Error(
                         `Addon "${scope}" module "${module}" has no register() export`,
                     )
                 }
-                if (!didRegister.current) {
-                    didRegister.current = true
-                    await Promise.resolve(register(api))
-                }
+                // Drop leftover contributions from a previous fiber of this key
+                // before the new register() runs (idempotent if none).
+                if (owner && hostRegistry) hostRegistry.unbind(owner)
+                const ret = await Promise.resolve(plugin.register(api))
+                disposeRef.current = composeDisposables(
+                    disposableFromRegisterResult(ret),
+                    plugin.dispose,
+                )
                 setStatus('ready')
                 onReady?.()
             } catch (e: unknown) {
@@ -176,8 +188,15 @@ export function AddonLoader({
         })()
         return () => {
             cancelled = true
+            const d = disposeRef.current
+            disposeRef.current = undefined
+            void runDispose(d)
+            if (owner && hostRegistry) hostRegistry.unbind(owner)
         }
-    }, [scope, url, module])
+        // api identity is expected to be stable per addon; including it would
+        // re-register on every parent render. Fiber identity is (scope, url, module).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [scope, url, module, addonKey, unbindKey, hostRegistry])
 
     if (status === 'loading') return <>{fallback}</>
     if (status === 'error')

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,
@@ -122,6 +135,17 @@ export {
     type ActionPlacement,
 } from './model-action-toolbar'
 export * from './addon-loader'
+export {
+    PURGE_ADDON_MESSAGE,
+    isAddonFrontendCacheUrl,
+    purgeAddonFrontendCache,
+    resolvePluginExports,
+    composeDisposables,
+    runDispose,
+    type PurgeAddonMessage,
+    type AddonRegisterModule,
+    type ResolvedPlugin,
+} from './addon-fiber'
 export {
     AddonLayoutProvider,
     useAddonLayout,

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

package/src/validation-catalog.ts

@@ -0,0 +1,60 @@
+/** Laravel-style validation catalogs. Hosts override any key via i18next
+ *  `validation.<code>`; these are the defaults when the key is missing, picked
+ *  by the operator's language (es by default — the product language). */
+
+export const VALIDATION_CATALOGS: Record<string, Record<string, string>> = {
+    es: {
+        failed: 'Revisa los campos marcados',
+        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',
+        min: 'El campo {{label}} debe ser al menos {{min}}',
+        min_length: '{{label}} debe tener al menos {{min}} caracteres',
+        max: 'El campo {{label}} no puede ser mayor que {{max}}',
+        max_length: '{{label}} no puede tener más de {{max}} caracteres',
+        regex: 'El formato de {{label}} no es válido',
+        email: '{{label}} debe ser un correo válido',
+        uuid: '{{label}} no es un identificador válido',
+        url: '{{label}} debe ser una URL válida',
+        numeric: '{{label}} debe ser un número',
+        integer: '{{label}} debe ser un entero',
+        custom: '{{label}} no es válido',
+        line_items_required: '{{label}} requiere al menos un renglón',
+        fallback: '{{label}}: valor inválido',
+    },
+    en: {
+        failed: 'Please check the highlighted fields',
+        required: 'The {{label}} field is required',
+        invalid_option: 'The selected {{label}} is invalid',
+        not_found: 'The selected {{label}} does not exist',
+        duplicate: 'A record with that {{label}} already exists',
+        invalid_type: 'The {{label}} field has an invalid format',
+        min: 'The {{label}} must be at least {{min}}',
+        min_length: 'The {{label}} must be at least {{min}} characters',
+        max: 'The {{label}} may not be greater than {{max}}',
+        max_length: 'The {{label}} may not be greater than {{max}} characters',
+        regex: 'The {{label}} format is invalid',
+        email: 'The {{label}} must be a valid email address',
+        uuid: 'The {{label}} is not a valid identifier',
+        url: 'The {{label}} must be a valid URL',
+        numeric: 'The {{label}} must be a number',
+        integer: 'The {{label}} must be an integer',
+        custom: 'The {{label}} is invalid',
+        line_items_required: '{{label}} requires at least one row',
+        fallback: '{{label}}: invalid value',
+    },
+}
+
+export function validationCatalog(language?: string): Record<string, string> {
+    const short = (language ?? 'es').split(/[-_]/)[0]!.toLowerCase()
+    return VALIDATION_CATALOGS[short] ?? VALIDATION_CATALOGS.es!
+}
+
+/** Pick the catalog key for a code, folding min/max + kind=length into *_length. */
+export function validationMessageKey(code: string, params?: Record<string, unknown>): string {
+    if (code === 'min' && params?.kind === 'length') return 'min_length'
+    if (code === 'max' && params?.kind === 'length') return 'max_length'
+    return code
+}