@resistdesign/voltra 3.0.0-alpha.33 → 3.0.0-alpha.34

package/README.md

@@ -131,8 +131,10 @@ EasyLayout now has:
 - Client routing: `examples/routing/app-routing.ts`
 - Backend API routing: `examples/api/backend-routing.ts`
 - Forms: `examples/forms/`
+  - `examples/forms/auto-form-validation-customization.tsx`
 - Layout: `examples/layout/`
 - Common types: `examples/common/types.ts`
+  - `examples/common/typeinfo-validation.ts`
 - Build-time parsing: `examples/build/type-parsing.ts`
 
 ### Template syntax
@@ -191,12 +193,13 @@ const coords = layout.computeNativeCoords({
 
 ## Routing (Web + Native)
 
-Voltra routing is unified under `@resistdesign/voltra/app`.
+Voltra routing uses the same `Route` API across app/web/native.
+Use the platform barrel for root `Route` so runtime mechanics are auto-wired.
 
 Reference example: `examples/routing/app-routing.ts`
 
 ```tsx
-import { Route } from "@resistdesign/voltra/app";
+import { Route } from "@resistdesign/voltra/web";
 
 <Route>
   <Route path="/" exact>
@@ -211,6 +214,16 @@ import { Route } from "@resistdesign/voltra/app";
 </Route>;
 ```
 
+```tsx
+import { Route } from "@resistdesign/voltra/native";
+
+<Route>
+  <Route path="/" exact>
+    <HomeScreen />
+  </Route>
+</Route>;
+```
+
 How it works:
 
 - Root `<Route>` (no `path`) is provider mode.
@@ -311,6 +324,63 @@ Renderers emit actions via:
 
 Use these to wire modals, selectors, or editors without baking UI into the core engine.
 
+### Centralized Validation
+
+All TypeInfo data-item validation can be run directly from `@resistdesign/voltra/common`:
+
+```ts
+import { validateTypeInfoDataItem } from "@resistdesign/voltra/common";
+```
+
+`validateTypeInfoDataItem` supports:
+
+- field-level `customValidatorMap` callbacks that return `ErrorDescriptor`
+- `tags.validation` field options:
+  - `validateHidden`
+  - `validateReadonly`
+  - `emptyArrayIsValid`
+
+AutoForm passes validation through the same centralized logic and supports:
+
+- `customValidatorMap` for app-specific rules
+- `translateValidationErrorCode` for UI-facing messages
+- multiple value-level errors per field
+- per-index array item errors for array fields
+
+Validation error maps can include both value-level errors and array item errors:
+
+```ts
+{
+  errorMap: {
+    title: [
+      { code: "MISSING_FIELD_VALUE" },
+      { code: "VALUE_DOES_NOT_MATCH_PATTERN" }
+    ],
+    tags: [
+      { code: "INVALID_TYPE" },
+      {
+        itemErrorMap: {
+          0: [{ code: "NOT_A_STRING" }],
+          2: [
+            { code: "NOT_A_STRING" },
+            { code: "INVALID_CUSTOM_TYPE" }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+- Field-level multiple errors are represented by multiple `ErrorDescriptor` entries in the field array.
+- Array item errors are represented by `itemErrorMap[index] = ErrorDescriptor[]`.
+
+Error-code constants are split by purpose:
+
+- `PRIMITIVE_ERROR_MESSAGE_CONSTANTS` keys follow `typeof` (`string`, `number`, `boolean`)
+- `DENIED_TYPE_OPERATIONS` keys follow `TypeOperation` (`CREATE`, `READ`, `UPDATE`, `DELETE`)
+- `ERROR_MESSAGE_CONSTANTS` exposes canonical code-keyed entries (for example `NOT_A_STRING`, `DENIED_TYPE_OPERATION_CREATE`)
+
 ## Docs Site
 
 The docs site is both reference documentation and a canonical usage example.

package/api/index.js

@@ -1,6 +1,5 @@
-import { ERROR_MESSAGE_CONSTANTS, validateTypeOperationAllowed, getValidityValue, validateTypeInfoValue, validateTypeInfoFieldValue } from '../chunk-LGM75I6P.js';
 import { ITEM_RELATIONSHIP_DAC_RESOURCE_NAME, ComparisonOperators } from '../chunk-7AMEFPPP.js';
-import '../chunk-IWRHGGGH.js';
+import { getNoErrorDescriptor, getErrorDescriptor, ERROR_MESSAGE_CONSTANTS, validateTypeOperationAllowed, getValidityValue, validateTypeInfoValue, validateTypeInfoFieldValue } from '../chunk-WTD5BBJP.js';
 import { mergeStringPaths, getPathString, getPathArray } from '../chunk-GYWRAW3Y.js';
 import '../chunk-I2KLQ2HA.js';
 import { QueryCommand, GetItemCommand, BatchGetItemCommand, BatchWriteItemCommand, DynamoDBClient, PutItemCommand, UpdateItemCommand, DeleteItemCommand, ScanCommand } from '@aws-sdk/client-dynamodb';
@@ -4361,6 +4360,9 @@ var getFilterTypeInfoDataItemsBySearchCriteria = (searchCriteria, items, typeInf
   for (const currentItem of items) {
     if (typeof currentItem === "object" && currentItem !== null) {
       let meetsCriteria = true;
+      if (logicalOperator === "OR" /* OR */ && fieldCriteria.length > 0) {
+        meetsCriteria = false;
+      }
       for (const fieldCriterion of fieldCriteria) {
         const { fieldName } = fieldCriterion;
         const { array: isArrayType, typeReference } = fields[fieldName] || {};
@@ -6477,7 +6479,7 @@ var validateSearchFields = (typeInfoName, typeInfoMap, searchFields = [], disall
   const results = {
     typeName: typeInfoName,
     valid: true,
-    error: "",
+    error: getNoErrorDescriptor(),
     errorMap: {}
   };
   if (typeInfo) {
@@ -6487,7 +6489,7 @@ var validateSearchFields = (typeInfoName, typeInfoMap, searchFields = [], disall
       if (!customOperator && (!operator || !Object.values(ComparisonOperators).includes(operator))) {
         results.valid = false;
         results.errorMap[fieldName] = [
-          SEARCH_VALIDATION_ERRORS.INVALID_OPERATOR
+          getErrorDescriptor(SEARCH_VALIDATION_ERRORS.INVALID_OPERATOR)
         ];
       } else {
         const tIF = fields[fieldName];
@@ -6497,12 +6499,14 @@ var validateSearchFields = (typeInfoName, typeInfoMap, searchFields = [], disall
           if (denyRead) {
             results.valid = false;
             results.errorMap[fieldName] = [
-              SEARCH_VALIDATION_ERRORS.INVALID_FIELD
+              getErrorDescriptor(SEARCH_VALIDATION_ERRORS.INVALID_FIELD)
             ];
           } else if (typeReference) {
             results.valid = false;
             results.errorMap[fieldName] = [
-              SEARCH_VALIDATION_ERRORS.RELATIONAL_FIELDS_NOT_ALLOWED
+              getErrorDescriptor(
+                SEARCH_VALIDATION_ERRORS.RELATIONAL_FIELDS_NOT_ALLOWED
+              )
             ];
           } else {
             if (operator && OPERATORS_WITHOUT_VALUES.has(operator)) {
@@ -6514,7 +6518,7 @@ var validateSearchFields = (typeInfoName, typeInfoMap, searchFields = [], disall
                 tVO,
                 tIF,
                 typeInfoMap,
-                false,
+                true,
                 true,
                 customValidators,
                 "READ" /* READ */,
@@ -6532,14 +6536,14 @@ var validateSearchFields = (typeInfoName, typeInfoMap, searchFields = [], disall
         } else {
           results.valid = false;
           results.errorMap[fieldName] = [
-            SEARCH_VALIDATION_ERRORS.INVALID_FIELD
+            getErrorDescriptor(SEARCH_VALIDATION_ERRORS.INVALID_FIELD)
           ];
         }
       }
     }
   } else {
     results.valid = false;
-    results.error = SEARCH_VALIDATION_ERRORS.INVALID_TYPE_INFO;
+    results.error = getErrorDescriptor(SEARCH_VALIDATION_ERRORS.INVALID_TYPE_INFO);
   }
   return results;
 };
@@ -6555,7 +6559,7 @@ var validateRelationshipItem = (relationshipItem, omitFields) => {
   const results = {
     typeName: fromTypeName,
     valid: true,
-    error: "",
+    error: getNoErrorDescriptor(),
     errorMap: {}
   };
   if (typeof relationshipItem === "object" && relationshipItem !== null) {
@@ -6568,24 +6572,34 @@ var validateRelationshipItem = (relationshipItem, omitFields) => {
         universalRKV in relationshipItem && typeof relationshipItem[universalRKV] !== "string" || omitRKV && universalRKV in relationshipItem
       ) {
         results.valid = false;
-        results.error = TYPE_INFO_ORM_RELATIONSHIP_ERRORS.INVALID_RELATIONSHIP_ITEM;
+        results.error = getErrorDescriptor(
+          TYPE_INFO_ORM_RELATIONSHIP_ERRORS.INVALID_RELATIONSHIP_ITEM
+        );
         results.errorMap[rKV] = [
-          TYPE_INFO_ORM_RELATIONSHIP_ERRORS.INVALID_RELATIONSHIP_ITEM_FIELD
+          getErrorDescriptor(
+            TYPE_INFO_ORM_RELATIONSHIP_ERRORS.INVALID_RELATIONSHIP_ITEM_FIELD
+          )
         ];
       } else if (
         // Missing Field
         !omitRKV && (!(universalRKV in relationshipItem) || !relationshipItem[universalRKV])
       ) {
         results.valid = false;
-        results.error = TYPE_INFO_ORM_RELATIONSHIP_ERRORS.INVALID_RELATIONSHIP_ITEM;
+        results.error = getErrorDescriptor(
+          TYPE_INFO_ORM_RELATIONSHIP_ERRORS.INVALID_RELATIONSHIP_ITEM
+        );
         results.errorMap[rKV] = [
-          TYPE_INFO_ORM_RELATIONSHIP_ERRORS.MISSING_RELATIONSHIP_ITEM_FIELD
+          getErrorDescriptor(
+            TYPE_INFO_ORM_RELATIONSHIP_ERRORS.MISSING_RELATIONSHIP_ITEM_FIELD
+          )
         ];
       }
     }
   } else {
     results.valid = false;
-    results.error = TYPE_INFO_ORM_RELATIONSHIP_ERRORS.INVALID_RELATIONSHIP_ITEM;
+    results.error = getErrorDescriptor(
+      TYPE_INFO_ORM_RELATIONSHIP_ERRORS.INVALID_RELATIONSHIP_ITEM
+    );
   }
   return results;
 };
@@ -6594,13 +6608,7 @@ var validateRelationshipItem = (relationshipItem, omitFields) => {
 var removeNonexistentFieldsFromSelectedFields = (typeInfo = {}, selectedFields) => {
   if (Array.isArray(selectedFields)) {
     const { fields = {} } = typeInfo;
-    const cleanSelectFields = [];
-    for (const tIF in fields) {
-      if (selectedFields.includes(tIF)) {
-        cleanSelectFields.push(tIF);
-      }
-    }
-    return cleanSelectFields;
+    return selectedFields.filter((field) => Boolean(fields[field]));
   } else {
     return selectedFields;
   }
@@ -6608,14 +6616,10 @@ var removeNonexistentFieldsFromSelectedFields = (typeInfo = {}, selectedFields)
 var removeTypeReferenceFieldsFromSelectedFields = (typeInfo = {}, selectedFields) => {
   if (Array.isArray(selectedFields)) {
     const { fields = {} } = typeInfo;
-    const cleanSelectFields = [];
-    for (const tIF in fields) {
-      const { typeReference } = fields[tIF];
-      if (typeof typeReference === "undefined" && selectedFields.includes(tIF)) {
-        cleanSelectFields.push(tIF);
-      }
-    }
-    return cleanSelectFields;
+    return selectedFields.filter((field) => {
+      const typeInfoField = fields[field];
+      return typeInfoField && typeof typeInfoField.typeReference === "undefined";
+    });
   } else {
     return selectedFields;
   }
@@ -7583,7 +7587,7 @@ var TypeInfoORMService = class {
     const results = {
       typeName,
       valid: !!typeInfo,
-      error: !!typeInfo ? "" : ERROR_MESSAGE_CONSTANTS.TYPE_DOES_NOT_EXIST,
+      error: !!typeInfo ? getNoErrorDescriptor() : getErrorDescriptor(ERROR_MESSAGE_CONSTANTS.TYPE_DOES_NOT_EXIST),
       errorMap: {}
     };
     const {
@@ -7602,7 +7606,7 @@ var TypeInfoORMService = class {
       const existingError = results.errorMap[oE] ?? [];
       results.errorMap[oE] = existingError ? [...existingError, ...operationErrorMap[oE]] : operationErrorMap[oE];
     }
-    if (!operationValid && operationError) {
+    if (!operationValid && operationError.code !== ERROR_MESSAGE_CONSTANTS.NONE) {
       results.error = operationError;
     }
     if (!results.valid) {
@@ -7701,7 +7705,7 @@ var TypeInfoORMService = class {
         const relationshipValidationResults = {
           typeName: fromTypeName,
           valid: false,
-          error: "INVALID_RELATIONSHIP" /* INVALID_RELATIONSHIP */,
+          error: getErrorDescriptor("INVALID_RELATIONSHIP" /* INVALID_RELATIONSHIP */),
           errorMap: {}
         };
         throw relationshipValidationResults;
@@ -8111,7 +8115,9 @@ var TypeInfoORMService = class {
       const validationResults = {
         typeName,
         valid: false,
-        error: "NO_PRIMARY_FIELD_VALUE_SUPPLIED" /* NO_PRIMARY_FIELD_VALUE_SUPPLIED */,
+        error: getErrorDescriptor(
+          "NO_PRIMARY_FIELD_VALUE_SUPPLIED" /* NO_PRIMARY_FIELD_VALUE_SUPPLIED */
+        ),
         errorMap: {}
       };
       throw validationResults;
@@ -8460,6 +8466,13 @@ var getHeadersWithCORS = (origin = "", corsPatterns = []) => {
 };
 
 // src/common/Logging/Utils.ts
+var stringifyForLog = (value) => {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch (error) {
+    return "[Unserializable]";
+  }
+};
 var logFunctionCall = async (label, args, functionRef, enabled) => {
   if (enabled) {
     console.log(
@@ -8467,7 +8480,7 @@ var logFunctionCall = async (label, args, functionRef, enabled) => {
       "INPUT" /* INPUT */,
       label,
       ":",
-      JSON.stringify(args, null, 2)
+      stringifyForLog(args)
     );
   }
   try {
@@ -8478,7 +8491,7 @@ var logFunctionCall = async (label, args, functionRef, enabled) => {
         "OUTPUT" /* OUTPUT */,
         label,
         ":",
-        JSON.stringify(result, null, 2)
+        stringifyForLog(result)
       );
     }
     return result;

package/app/forms/Engine.d.ts

@@ -5,6 +5,7 @@
  */
 import type { TypeInfo } from "../../common/TypeParsing/TypeInfo";
 import { TypeOperation } from "../../common/TypeParsing/TypeInfo";
+import { type FieldValueValidatorMap } from "../../common/TypeParsing/Validation";
 import type { FormController, FormValues } from "./types";
 /**
  * Hook that derives form state and field controllers from type metadata.
@@ -17,4 +18,6 @@ import type { FormController, FormValues } from "./types";
 export declare const useFormEngine: (initialValues: FormValues | undefined, typeInfo: TypeInfo, options?: {
     /** Operation to evaluate when deriving field state. */
     operation?: TypeOperation;
+    /** Optional custom validators keyed by field name. */
+    customValidatorMap?: FieldValueValidatorMap;
 }) => FormController;

package/app/forms/UI.d.ts

@@ -6,7 +6,7 @@
 import { FC } from "react";
 import type { ReactElement } from "react";
 import type { TypeInfo, TypeOperation } from "../../common/TypeParsing/TypeInfo";
-import type { AutoFieldProps, CustomTypeActionPayload, FormController, FormValues, RelationActionPayload } from "./types";
+import type { AutoFieldProps, CustomValidatorMap, CustomTypeActionPayload, FormController, FormValues, RelationActionPayload, TranslateValidationErrorCode } from "./types";
 import type { ResolvedSuite } from "./core/types";
 /**
  * Renderer contract used by shared AutoForm components.
@@ -33,6 +33,8 @@ export interface AutoFormViewProps {
     onRelationAction?: (payload: RelationActionPayload) => void;
     /** Optional custom type action handler. */
     onCustomTypeAction?: (payload: CustomTypeActionPayload) => void;
+    /** Optional translator for validation error descriptors. */
+    translateValidationErrorCode?: TranslateValidationErrorCode;
 }
 /**
  * Render a form UI from a prepared form controller.
@@ -63,6 +65,10 @@ export interface AutoFormProps {
     operation?: TypeOperation;
     /** Disable the submit button when true. */
     submitDisabled?: boolean;
+    /** Optional translator for validation error descriptors. */
+    translateValidationErrorCode?: TranslateValidationErrorCode;
+    /** Optional custom validators keyed by field name. */
+    customValidatorMap?: CustomValidatorMap;
 }
 /**
  * Build a controller from type metadata and render an auto form.

package/app/forms/core/createAutoField.d.ts

@@ -3,7 +3,9 @@
  *
  * Factory for AutoField that delegates rendering to a resolved suite.
  */
+import { type FC, type ReactElement } from "react";
 import type { TypeInfoField } from "../../../common/TypeParsing/TypeInfo";
+import { type ErrorDescriptor, type ArrayItemErrorMap } from "../../../common/TypeParsing/Validation";
 import type { CustomTypeActionPayload, FieldValue, RelationActionPayload, ResolvedSuite } from "./types";
 /**
  * Input props for AutoField render delegation.
@@ -17,8 +19,14 @@ export type AutoFieldInput = {
     value: FieldValue | undefined;
     /** Change handler for the field value. */
     onChange: (value: FieldValue) => void;
-    /** Optional error message to display under the field. */
-    error?: string;
+    /** Optional error descriptor to display under the field. */
+    error?: ErrorDescriptor;
+    /** Optional value-level errors for the field. */
+    errors?: ErrorDescriptor[];
+    /** Optional per-index errors for array fields. */
+    arrayItemErrorMap?: ArrayItemErrorMap;
+    /** Optional translator for validation error descriptors. */
+    translateValidationErrorCode?: (error: ErrorDescriptor) => string;
     /** Disables the field UI when true. */
     disabled?: boolean;
     /** Optional callback for relation actions. */
@@ -32,4 +40,4 @@ export type AutoFieldInput = {
  * @param suite - Resolved component suite.
  * @returns AutoField renderer function.
  */
-export declare const createAutoField: <RenderOutput = unknown>(suite: ResolvedSuite<RenderOutput>) => (props: AutoFieldInput) => RenderOutput;
+export declare const createAutoField: <RenderOutput = ReactElement>(suite: ResolvedSuite<RenderOutput>) => FC<AutoFieldInput>;

package/app/forms/core/createFormRenderer.d.ts

@@ -3,6 +3,7 @@
  *
  * Factory for building form renderers backed by component suites.
  */
+import type { ReactElement } from "react";
 import type { ResolvedSuite, ComponentSuite } from "./types";
 import { type AutoFieldInput } from "./createAutoField";
 /**
@@ -11,11 +12,11 @@ import { type AutoFieldInput } from "./createAutoField";
  * @param options - Suite configuration.
  * @returns Renderer helpers tied to resolved suites.
  */
-export declare const createFormRenderer: <RenderOutput = unknown>(options: {
+export declare const createFormRenderer: <RenderOutput = ReactElement>(options: {
     fallbackSuite: ComponentSuite<RenderOutput>;
     suite?: ComponentSuite<RenderOutput>;
 }) => {
-    AutoField: (props: AutoFieldInput) => RenderOutput;
+    AutoField: import("react").FC<AutoFieldInput>;
     suite: ResolvedSuite<RenderOutput>;
 };
 /**

package/app/forms/core/mergeSuites.d.ts

@@ -3,6 +3,7 @@
  *
  * Helpers for composing component suites.
  */
+import type { ReactElement } from "react";
 import type { ComponentSuite, FieldKind, FieldRenderer } from "./types";
 /**
  * Deep-merge component suites, allowing overrides for renderers and primitives.
@@ -11,7 +12,7 @@ import type { ComponentSuite, FieldKind, FieldRenderer } from "./types";
  * @param overrides - Partial suite overrides.
  * @returns Merged suite.
  */
-export declare const mergeSuites: <RenderOutput = unknown>(base: ComponentSuite<RenderOutput>, overrides: ComponentSuite<RenderOutput>) => ComponentSuite<RenderOutput>;
+export declare const mergeSuites: <RenderOutput = ReactElement>(base: ComponentSuite<RenderOutput>, overrides: ComponentSuite<RenderOutput>) => ComponentSuite<RenderOutput>;
 /**
  * Convenience helper to override a single renderer.
  *
@@ -19,4 +20,4 @@ export declare const mergeSuites: <RenderOutput = unknown>(base: ComponentSuite<
  * @param renderer - Replacement renderer.
  * @returns Suite with renderer override.
  */
-export declare const withRendererOverride: <RenderOutput = unknown>(kind: FieldKind, renderer: FieldRenderer<RenderOutput>) => ComponentSuite<RenderOutput>;
+export declare const withRendererOverride: <RenderOutput = ReactElement>(kind: FieldKind, renderer: FieldRenderer<RenderOutput>) => ComponentSuite<RenderOutput>;

package/app/forms/core/resolveSuite.d.ts

@@ -3,6 +3,7 @@
  *
  * Resolve a component suite by merging overrides with fallback defaults.
  */
+import type { ReactElement } from "react";
 import type { ComponentSuite, ResolvedSuite } from "./types";
 /**
  * Merge a fallback suite with overrides and ensure completeness.
@@ -11,4 +12,4 @@ import type { ComponentSuite, ResolvedSuite } from "./types";
  * @param fallback - Default suite providing full coverage.
  * @returns Fully resolved suite with all renderers present.
  */
-export declare const resolveSuite: <RenderOutput = unknown>(overrides: ComponentSuite<RenderOutput> | undefined, fallback: ComponentSuite<RenderOutput>) => ResolvedSuite<RenderOutput>;
+export declare const resolveSuite: <RenderOutput = ReactElement>(overrides: ComponentSuite<RenderOutput> | undefined, fallback: ComponentSuite<RenderOutput>) => ResolvedSuite<RenderOutput>;

package/app/forms/core/types.d.ts

@@ -3,7 +3,9 @@
  *
  * Core, platform-agnostic types for form rendering.
  */
+import type { ComponentType, ReactElement } from "react";
 import type { LiteralValue, TypeInfoDataItem, TypeInfoField } from "../../../common/TypeParsing/TypeInfo";
+import type { ArrayItemErrorMap, ErrorDescriptor } from "../../../common/TypeParsing/Validation";
 import type { ItemRelationshipInfoType } from "../../../common/ItemRelationshipInfoTypes";
 /**
  * Supported field kinds for renderer selection.
@@ -77,8 +79,14 @@ export type FieldRenderContext<RenderOutput = unknown> = {
     required: boolean;
     /** True when the field UI should be disabled. */
     disabled: boolean;
-    /** Optional error message to display under the field. */
-    error?: string;
+    /** Optional error descriptor to display under the field. */
+    error?: ErrorDescriptor;
+    /** Optional value-level errors for the field. */
+    errors?: ErrorDescriptor[];
+    /** Optional per-index errors for array fields. */
+    arrayItemErrorMap?: ArrayItemErrorMap;
+    /** Translate an error descriptor to a user-facing message. */
+    translateValidationErrorCode: (error: ErrorDescriptor) => string;
     /** Current value for the field. */
     value: FieldValue | undefined;
     /** Change handler for the field value. */
@@ -103,24 +111,27 @@ export type FieldRenderContext<RenderOutput = unknown> = {
         fieldKey: string;
         value: FieldValue | undefined;
         onChange: (value: FieldValue) => void;
-        error?: string;
+        error?: ErrorDescriptor;
+        errors?: ErrorDescriptor[];
+        arrayItemErrorMap?: ArrayItemErrorMap;
+        translateValidationErrorCode?: (error: ErrorDescriptor) => string;
         disabled?: boolean;
         onRelationAction?: (payload: RelationActionPayload) => void;
         onCustomTypeAction?: (payload: CustomTypeActionPayload) => void;
     }) => RenderOutput;
 };
 /**
- * Renderer function for a single field kind.
+ * Renderer component for a single field kind.
  */
-export type FieldRenderer<RenderOutput = unknown> = (context: FieldRenderContext<RenderOutput>) => RenderOutput;
+export type FieldRenderer<RenderOutput = ReactElement> = ComponentType<FieldRenderContext<RenderOutput>>;
 /**
  * Optional primitive component contract for suites.
  */
-export type PrimitiveComponent<Props, RenderOutput = unknown> = (props: Props) => RenderOutput;
+export type PrimitiveComponent<Props, RenderOutput = ReactElement> = (props: Props) => RenderOutput;
 /**
  * Primitive components that suites may override.
  */
-export type PrimitiveComponents<RenderOutput = unknown> = {
+export type PrimitiveComponents<RenderOutput = ReactElement> = {
     /** Root container for the form view. */
     FormRoot: PrimitiveComponent<{
         children: RenderOutput;
@@ -151,7 +162,7 @@ export type PrimitiveComponents<RenderOutput = unknown> = {
 /**
  * Suite definition with optional renderers/primitives.
  */
-export type ComponentSuite<RenderOutput = unknown> = {
+export type ComponentSuite<RenderOutput = ReactElement> = {
     /** Field renderers keyed by kind. */
     renderers: Partial<Record<FieldKind, FieldRenderer<RenderOutput>>>;
     /** Optional primitive component overrides. */
@@ -160,7 +171,7 @@ export type ComponentSuite<RenderOutput = unknown> = {
 /**
  * Fully resolved suite with required renderers.
  */
-export type ResolvedSuite<RenderOutput = unknown> = {
+export type ResolvedSuite<RenderOutput = ReactElement> = {
     /** Field renderers keyed by kind. */
     renderers: Record<FieldKind, FieldRenderer<RenderOutput>>;
     /** Optional primitive component overrides. */

package/app/forms/types.d.ts

@@ -4,8 +4,17 @@
  * Types for the form generation system.
  */
 import type { TypeInfo, TypeInfoDataItem, TypeInfoField, TypeOperation } from "../../common/TypeParsing/TypeInfo";
+import type { ArrayErrorDescriptorCollection, ArrayItemErrorMap, ErrorDescriptor, FieldValueValidatorMap, TypeInfoValidationResults } from "../../common/TypeParsing/Validation";
 import type { CustomTypeActionPayload, RelationActionPayload } from "./core/types";
 export * from "./core/types";
+/**
+ * Translates validation error descriptors into UI messages.
+ */
+export type TranslateValidationErrorCode = (error: ErrorDescriptor) => string;
+/**
+ * Optional custom field validators keyed by field name.
+ */
+export type CustomValidatorMap = FieldValueValidatorMap;
 /**
  * Loose map of form values keyed by field.
  */
@@ -47,8 +56,14 @@ export interface AutoFieldProps {
     value: FormValue | undefined;
     /** Change handler for the field value. */
     onChange: (value: FormValue) => void;
-    /** Optional error message to display under the field. */
-    error?: string;
+    /** Optional primary error descriptor for convenience/backward compatibility. */
+    error?: ErrorDescriptor;
+    /** Optional list of value-level errors for the field. */
+    errors?: ErrorDescriptor[];
+    /** Optional per-index errors for array fields. */
+    arrayItemErrorMap?: ArrayItemErrorMap;
+    /** Optional translator from error descriptor to user-facing message. */
+    translateValidationErrorCode?: TranslateValidationErrorCode;
     /** Disables the field UI when true. */
     disabled?: boolean;
     /** Optional callback for relation actions. */
@@ -82,9 +97,21 @@ export type FormFieldController = {
     value: FormValue | undefined;
     /** Change handler for the field value. */
     onChange: (value: FormValue) => void;
-    /** Optional error message for the field. */
-    error?: string;
+    /** Optional primary error descriptor for the field. */
+    error?: ErrorDescriptor;
+    /** Optional list of value-level errors for the field. */
+    errors?: ErrorDescriptor[];
+    /** Optional per-index errors for array fields. */
+    arrayItemErrorMap?: ArrayItemErrorMap;
 };
+/**
+ * Validation errors keyed by field and represented as descriptors/codes.
+ */
+export type FormErrorMap = Record<string, (ErrorDescriptor | ArrayErrorDescriptorCollection)[]>;
+/**
+ * Input map used to set form errors, accepting descriptors or raw codes.
+ */
+export type FormErrorInputMap = Record<string, ErrorDescriptor | string | ErrorDescriptor[] | ArrayItemErrorMap | (ErrorDescriptor | ArrayErrorDescriptorCollection)[]>;
 /**
  * Controller for a form instance and its fields.
  */
@@ -98,13 +125,13 @@ export type FormController = {
     /** Current form values keyed by field. */
     values: FormValues;
     /** Validation errors keyed by field. */
-    errors: Record<string, string>;
+    errors: FormErrorMap;
     /** Derived controllers for each field. */
     fields: FormFieldController[];
     /** Update a field value by key. */
     setFieldValue: (key: string, value: FormValue) => void;
     /** Validate the form and return success. */
-    validate: () => boolean;
+    validate: () => TypeInfoValidationResults;
     /** Override form errors with a provided map. */
-    setErrors: (errors: Record<string, string>) => void;
+    setErrors: (errors: FormErrorInputMap) => void;
 };