feat(form): add custom validation message component and improve validation message system

Ohh-889 · Ohh-889 · commit 55e290103c64 · 2025-10-01T17:41:42.000+08:00
diff --git a/playground/src/app/(demo)/form/modules/CustomValidateMessages.tsx b/playground/src/app/(demo)/form/modules/CustomValidateMessages.tsx
@@ -0,0 +1,70 @@
+/* eslint-disable no-template-curly-in-string */
+'use client';
+
+import { Button, Card, Form, FormField, Input, useForm } from 'soybean-react-ui';
+
+// Form field types
+type Inputs = {
+  age: number;
+  email: string;
+  username: string;
+};
+
+const initialValues: Inputs = {
+  age: 0,
+  email: '',
+  username: ''
+};
+
+const ValidateMessagesDemo = () => {
+  const [form] = useForm<Inputs>();
+
+  return (
+    <Card title="Form with custom validateMessages">
+      <Form
+        className="w-[480px] max-sm:w-full space-y-4"
+        form={form}
+        initialValues={initialValues}
+        validateMessages={{
+          number: {
+            min: 'This field must be greater than ${min}'
+          },
+          required: 'This field must be required'
+        }}
+      >
+        <FormField
+          label="Username"
+          name="username"
+          rules={[{ required: true }]}
+        >
+          <Input placeholder="Enter username" />
+        </FormField>
+
+        <FormField
+          label="Age"
+          name="age"
+          rules={[{ min: 18, required: true, type: 'number' }]}
+        >
+          <Input
+            placeholder="Enter age"
+            type="number"
+          />
+        </FormField>
+
+        <FormField
+          label="Email"
+          name="email"
+          rules={[{ required: true, type: 'email' }]}
+        >
+          <Input placeholder="Enter email" />
+        </FormField>
+
+        <div className="flex gap-2">
+          <Button type="submit">Submit</Button>
+        </div>
+      </Form>
+    </Card>
+  );
+};
+
+export default ValidateMessagesDemo;
diff --git a/playground/src/app/(demo)/form/page.tsx b/playground/src/app/(demo)/form/page.tsx
@@ -1,6 +1,7 @@
 import AsyncValidatorResolver from './modules/AsyncValidatorResolver';
 import ClearDestroy from './modules/ClearDestroy';
 import ComputedDemo from './modules/ComputedDemo';
+import CustomValidateMessages from './modules/CustomValidateMessages';
 import Default from './modules/Default';
 import FieldChange from './modules/FieldChange';
 import List from './modules/List';
@@ -48,6 +49,8 @@ const FormPage = () => {
 
       <UndoRedo />
 
+      <CustomValidateMessages />
+
       <ClearDestroy />
     </div>
   );
diff --git a/primitives/filed-form /src/form-core/createStore.ts b/primitives/filed-form /src/form-core/createStore.ts
@@ -15,7 +15,7 @@ import { type ChangeMask, ChangeTag } from './event';
 import type { Action, ArrayOpArgs, Middleware, ValidateFieldsOptions } from './middleware';
 import { compose } from './middleware';
 import type { Callbacks, FieldEntity, Meta, Store, StoreValue } from './types';
-import type { ValidateMessages } from './validate';
+import { type ValidateMessages, defaultValidateMessages } from './validate';
 import { runRulesWithMode } from './validation';
 import type { Rule, ValidateOptions } from './validation';
 
@@ -95,7 +95,7 @@ class FormStore {
   /** Form lifecycle callbacks */
   private _callbacks: Callbacks = {};
   /** Validation message templates */
-  private _validateMessages: ValidateMessages = {};
+  private _validateMessages: ValidateMessages = defaultValidateMessages;
 
   // Status tracking sets
   /** Set of fields that have been touched by user interaction */
@@ -161,9 +161,6 @@ class FormStore {
   /** Set of hidden field keys */
   private _hiddenKeys = new Set<string>();
 
-  /** Transform functions to run before form submission */
-  private _preSubmit: Array<(values: Store) => Store> = [];
-
   /** Flag to preserve field values after unmount */
   private _preserve = false;
 
@@ -197,7 +194,7 @@ class FormStore {
    * Sets validation message templates
    */
   private setValidateMessages = (m: ValidateMessages) => {
-    this._validateMessages = m || {};
+    this._validateMessages = assign(defaultValidateMessages, m);
   };
 
   /**
@@ -887,7 +884,16 @@ class FormStore {
       let warns: string[] = [];
 
       try {
-        ({ errors, warns } = await runRulesWithMode(value, rules, 'parallelAll', this._store));
+        const { errors: validErrors, warns: validWarns } = await runRulesWithMode(
+          value,
+          rules,
+          'parallelAll',
+          this._store,
+          this._validateMessages
+        );
+
+        errors = validErrors;
+        warns = validWarns;
       } catch (e: any) {
         // 4) Fallback: convert thrown errors into messages (avoid silent pass/hang)
         errors = [String(e?.message ?? e)];
diff --git a/primitives/filed-form /src/form-core/validate.ts b/primitives/filed-form /src/form-core/validate.ts
@@ -1,49 +1,109 @@
+/* eslint-disable no-template-curly-in-string */
+/**
+ * Validation message system for form field validation
+ * Provides customizable error messages for different validation rule types
+ */
+
+/** Type alias for validation message strings */
 type ValidateMessage = string;
 
+/**
+ * Configuration object for validation error messages
+ * Supports nested message structures for different validation types
+ */
 export interface ValidateMessages {
-  array?: {
-    len?: ValidateMessage;
-    max?: ValidateMessage;
-    min?: ValidateMessage;
-    range?: ValidateMessage;
-  };
+  /** Error message for boolean type validation */
+  boolean?: ValidateMessage;
+
+  /** Error messages for date type validation */
   date?: {
-    format?: ValidateMessage;
     invalid?: ValidateMessage;
-    parse?: ValidateMessage;
+    max?: ValidateMessage;
+    min?: ValidateMessage;
   };
+
+  /** Default error message when no specific message is found */
   default?: ValidateMessage;
+
+  /** Error message for email format validation */
+  email?: ValidateMessage;
+
+  /** Error message for enum validation failure */
   enum?: ValidateMessage;
+
+  /** Error message for float type validation */
+  float?: ValidateMessage;
+
+  /** Error message for hex color validation */
+  hex?: ValidateMessage;
+
+  /** Error messages for integer type validation */
+  integer?: {
+    max?: ValidateMessage;
+    min?: ValidateMessage;
+  };
+
+  /** Error messages for number type validation */
   number?: {
     len?: ValidateMessage;
     max?: ValidateMessage;
     min?: ValidateMessage;
-    range?: ValidateMessage;
-  };
-  pattern?: {
-    mismatch?: ValidateMessage;
   };
+
+  /** Error message for regular expression validation */
+  regexp?: ValidateMessage;
+
+  /** Error message for required field validation */
   required?: ValidateMessage;
+
+  /** Error messages for string type validation */
   string?: {
     len?: ValidateMessage;
-    max?: ValidateMessage;
-    min?: ValidateMessage;
-    range?: ValidateMessage;
-  };
-  types?: {
-    array?: ValidateMessage;
-    boolean?: ValidateMessage;
-    date?: ValidateMessage;
-    email?: ValidateMessage;
-    float?: ValidateMessage;
-    hex?: ValidateMessage;
-    integer?: ValidateMessage;
-    method?: ValidateMessage;
-    number?: ValidateMessage;
-    object?: ValidateMessage;
-    regexp?: ValidateMessage;
-    string?: ValidateMessage;
-    url?: ValidateMessage;
+    maxLength?: ValidateMessage;
+    minLength?: ValidateMessage;
+    pattern?: ValidateMessage;
   };
+
+  /** Error message for URL format validation */
+  url?: ValidateMessage;
+
+  /** Error message for whitespace-only string validation */
   whitespace?: ValidateMessage;
 }
+
+/**
+ * Default validation message templates with placeholder support
+ * These messages can be customized by providing a ValidateMessages object
+ * Placeholders like ${min}, ${max}, ${len} are replaced with actual rule values
+ */
+export const defaultValidateMessages: ValidateMessages = {
+  boolean: 'Must be a boolean',
+  date: {
+    invalid: 'Must be a valid Date',
+    max: 'Date is later than maximum',
+    min: 'Date is earlier than minimum'
+  },
+  email: 'Must be a valid email',
+  enum: 'Value is not in enum',
+  float: 'Must be a float',
+  hex: 'Must be a valid hex color',
+  integer: {
+    max: 'Max is ${max}',
+    min: 'Min is ${min}'
+  },
+  number: {
+    len: 'Must equal ${len}',
+    max: 'Max is ${max}',
+    min: 'Min is ${min}'
+  },
+  regexp: 'Must be a valid regular expression',
+  required: 'This field is required',
+  string: {
+    len: 'Length must be ${len}',
+    maxLength: 'Max length is ${maxLength}',
+    minLength: 'Min length is ${minLength}',
+    pattern: 'Pattern not match'
+  },
+  url: 'Must be a valid URL',
+  whitespace: 'Only whitespace is not allowed'
+};
diff --git a/primitives/filed-form /src/form-core/validation.ts b/primitives/filed-form /src/form-core/validation.ts
