@rainbow-oh/yee-c 0.4.5 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-oh/yee-c",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "yee basic components",
   "keywords": [
     "react",

package/src/Dialog/demo/basic.tsx

@@ -22,7 +22,7 @@ export default () => {
           setOpen(false);
           // form.resetFields();
         }}
-        onConfirm={() => form.submit()}
+        onConfirm={() => void form.submit()}
       >
         <Form
           form={form}

package/src/Dialog/dialog.tsx

@@ -90,7 +90,7 @@ const Dialog = (baseprops: DialogProps) => {
   });
 
   const renderFooter = () => {
-    if (footer === false) {
+    if (footer === false || footer === null) {
       return null;
     }
 

package/src/Field/demo/validation.tsx

@@ -8,10 +8,10 @@ export default () => {
     createForm('validationForm');
   }, []);
 
-  const handleSubmit = () => {
+  const handleSubmit = async () => {
     const form = getForm('validationForm');
     console.log('form: ', form);
-    const errors = form?.submit();
+    const errors = await form?.submit();
     console.log('errors: ', errors);
     if (errors && errors.length === 0) {
       console.log('Submit success:', form?.getFieldsValue());

package/src/Field/field.tsx

@@ -82,7 +82,8 @@ const Field: FC<FieldProps> = (props) => {
         forceUpdate();
       },
       onBlur: (event: unknown) => {
-        validateField?.(name, 'onBlur');
+        // Fire-and-forget async validation; store notifies onStoreChange on completion.
+        void validateField?.(name, 'onBlur');
 
         // Call child component's onBlur
         if ((children.props as any).onBlur) {

package/src/Field/index.en-US.md

@@ -49,6 +49,6 @@ A standalone form field component that works without a `<Form>` wrapper. Uses `u
 | minLength | `number` | Minimum length | - |
 | maxLength | `number` | Maximum length | - |
 | regexp | `RegExp` | Regex pattern | - |
-| validator | `(value: unknown) => boolean` | Custom validation function | - |
+| validator | `(value: unknown) => boolean \| void \| Promise<boolean \| void>` | Custom validation function, supports sync and async (see Form.Rule) | - |
 | message | `string` | Error message (required) | - |
 | validateTrigger | `'onBlur' \| 'onChange' \| 'onSubmit' \| Array` | When to trigger validation | - |

package/src/Field/index.zh-CN.md

@@ -49,6 +49,6 @@ toc: 'content'
 | minLength | `number` | 最小长度 | - |
 | maxLength | `number` | 最大长度 | - |
 | regexp | `RegExp` | 正则校验 | - |
-| validator | `(value: unknown) => boolean` | 自定义校验函数 | - |
+| validator | `(value: unknown) => boolean \| void \| Promise<boolean \| void>` | 自定义校验函数，支持同步与异步（详见 Form.Rule） | - |
 | message | `string` | 错误提示信息（必填） | - |
 | validateTrigger | `'onBlur' \| 'onChange' \| 'onSubmit' \| Array` | 校验触发时机 | - |

package/src/Form/Field.tsx

@@ -139,10 +139,9 @@ const Field: React.FC<FieldProps> = (props) => {
         props?.onChange?.(_value, ...rest);
       },
       onBlur: (event: unknown) => {
-        const err = validateField?.(normalizedName, 'onBlur');
-        if (err.length) {
-          forceUpdate();
-        }
+        // Fire-and-forget; the store calls onStoreChange (→ forceUpdate) when
+        // the (possibly async) validation completes, so the error UI refreshes.
+        void validateField?.(normalizedName, 'onBlur');
         props?.onBlur?.(event);
       },
     };

package/src/Form/Form.tsx

@@ -60,7 +60,7 @@ const Form: React.FC<FormProps> = (baseprops) => {
       onSubmit={(e) => {
         e.preventDefault();
         e.stopPropagation();
-        formInstance.submit();
+        void formInstance.submit();
       }}
       onReset={(e) => {
         e.preventDefault();

package/src/Form/Group.tsx

@@ -9,6 +9,7 @@ import React, {
   useRef,
 } from 'react';
 import Grid from '../Grid';
+import { runValidator } from './utils/validate';
 import FieldContext from './FieldContext';
 import FormContext from './FormContext';
 import type { FieldGroupProps, NamePath, ValidateMessage } from './interface';
@@ -38,7 +39,9 @@ const Group: React.FC<FieldGroupProps> = (props) => {
   const [, forceValidate] = useReducer((x) => x + 1, 0); // eslint-disable-line @typescript-eslint/no-unused-vars
 
   // Group validation
-  const validate = (force: boolean): ValidateMessage[] => {
+  const validate = async (
+    force: boolean,
+  ): Promise<ValidateMessage[]> => {
     if (!required && (!rules || rules.length === 0)) return [];
 
     // Skip if not touched and not forced validation
@@ -66,21 +69,21 @@ const Group: React.FC<FieldGroupProps> = (props) => {
       }
     }
 
-    // Custom rules validation
+    // Custom rules validation (supports sync + async validators)
     if (rules) {
-      rules.forEach((rule) => {
+      for (const rule of rules) {
         if (rule.validator) {
-          const passed = rule.validator(values);
-          if (!passed) {
+          const result = await runValidator(rule.validator, values);
+          if (!result.passed) {
             errors.push({
               name: childNames,
               status: 'error',
               value: values,
-              message: rule.message || '',
+              message: result.message ?? rule.message ?? '',
             });
           }
         }
-      });
+      }
     }
 
     return errors;
@@ -92,8 +95,8 @@ const Group: React.FC<FieldGroupProps> = (props) => {
     [],
   );
 
-  const runValidation = () => {
-    const result = validate(false);
+  const runValidation = async () => {
+    const result = await validate(false);
     setErrors(result);
   };
 
@@ -102,7 +105,7 @@ const Group: React.FC<FieldGroupProps> = (props) => {
     const unsubscribes = childNames.map((name) =>
       formInstance.subscribe(name, () => {
         touchedRef.current = true;
-        runValidation();
+        void runValidation();
       }),
     );
     return () => unsubscribes.forEach((fn) => fn());
@@ -111,8 +114,8 @@ const Group: React.FC<FieldGroupProps> = (props) => {
   // Register group validator to FormStore
   useEffect(() => {
     const unregister = formInstance.registerGroupEntity(groupId, {
-      validate: (force) => {
-        const result = validate(force);
+      validate: async (force) => {
+        const result = await validate(force);
         setErrors(result);
         forceUpdate();
         return result;

package/src/Form/List.tsx

@@ -68,7 +68,7 @@ const List: React.FC<FormListProps> = ({
 
   // List operation methods
   const operations = useMemo(() => {
-    const add = (defaultValue?: any, insertIndex?: number) => {
+    const add = async (defaultValue?: any, insertIndex?: number) => {
       const currentValue = getListValue();
       const pathStr = prefixName.join('.');
 
@@ -83,8 +83,8 @@ const List: React.FC<FormListProps> = ({
         }
       });
 
-      // Execute validation
-      const errors = validateFields?.(fieldPaths);
+      // Execute validation (async — await before deciding whether to add)
+      const errors = await validateFields?.(fieldPaths);
 
       // If errors exist, prevent adding and show errors
       if (errors && errors.length > 0) {

package/src/Form/demo/async-validate.tsx

@@ -0,0 +1,71 @@
+import { Button, Form, Grid, Input, Space } from '@rainbow-oh/yee-c';
+import React from 'react';
+
+// Simulate an async uniqueness check against a backend API.
+const TAKEN_USERNAMES = new Set(['admin', 'root', 'test']);
+function checkUsernameUnique(username: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    setTimeout(() => resolve(!TAKEN_USERNAMES.has(username)), 600);
+  });
+}
+
+export default () => {
+  const [form] = Form.useForm();
+
+  const onFinish = (values: Record<string, unknown>) => {
+    console.log('Received values:', values);
+  };
+
+  const onFinishFailed = (errorInfo: unknown) => {
+    console.log('Failed:', errorInfo);
+  };
+
+  return (
+    <Form form={form} onFinish={onFinish} onFinishFailed={onFinishFailed}>
+      <Grid>
+        <Form.Field
+          name="username"
+          label="Username"
+          rules={[
+            { required: true, message: 'Please input your username!' },
+            {
+              // Async validator: resolve to pass, throw / reject to fail.
+              // The thrown Error's message overrides rule.message.
+              validator: async (value) => {
+                const isUnique = await checkUsernameUnique(String(value));
+                if (!isUnique) {
+                  throw new Error('This username is already taken');
+                }
+              },
+              // Validate on blur so we don't hit the "API" on every keystroke.
+              validateTrigger: 'onBlur',
+            },
+          ]}
+        >
+          <Input placeholder="Try admin / root / test (already taken)" />
+        </Form.Field>
+
+        <Form.Field
+          name="email"
+          label="Email"
+          rules={[
+            { required: true, message: 'Please input your email!' },
+            {
+              regexp: /^[\w.+-]+@[\w-]+\.[\w.-]+$/,
+              message: 'Please enter a valid email!',
+            },
+          ]}
+        >
+          <Input placeholder="Please input your email" />
+        </Form.Field>
+      </Grid>
+
+      <Space>
+        <Button type="primary" htmlType="submit">
+          Submit
+        </Button>
+        <Button htmlType="reset">Reset</Button>
+      </Space>
+    </Form>
+  );
+};

package/src/Form/demo/virtual.tsx

@@ -50,7 +50,7 @@ export default function Virtual() {
         type="primary"
         onClick={() => {
           const form = getForm('form');
-          form.submit();
+          void form.submit();
         }}
       >
         Submit

package/src/Form/form-store.ts

@@ -145,13 +145,14 @@ export class FormStore {
       });
     }
 
-    // Validate on onChange and onBlur
+    // Validate on onChange and onBlur (async — fire-and-forget so setFieldsValue
+    // stays synchronous for its callers; results surface via onStoreChange).
     if (
       trigger === 'onChange' ||
       trigger === 'onBlur' ||
       trigger === 'onSubmit'
     ) {
-      this.validateFields(Object.keys(newStore), trigger);
+      void this.validateFields(Object.keys(newStore), trigger);
     }
 
     this.refreshField(newStore);
@@ -202,7 +203,10 @@ export class FormStore {
     this.setFieldsValue(clearStore, 'clear');
   };
 
-  validateField = (name: Name, trigger?: TRIGGER) => {
+  validateField = async (
+    name: Name,
+    trigger?: TRIGGER,
+  ): Promise<ValidateMessage[]> => {
     const entity = this.fieldMap.get(name);
     if (!entity) {
       return [];
@@ -231,32 +235,40 @@ export class FormStore {
       });
     }
     const value = this.getFieldValue(name);
-    mergedRules.forEach((rule) => {
-      const mark = validate(rule, value);
-      if (name && !mark) {
+    for (const rule of mergedRules) {
+      const result = await validate(rule, value);
+      if (name && !result.passed) {
         err.push({
+          ...rule,
           name: name,
           status: 'error',
           value,
-          ...rule,
+          message: result.message ?? rule.message,
         } as ValidateMessage);
       }
-    });
+    }
     if (err.length > 0) {
       this.validateMessages.set(name, err);
     } else if (this.validateMessages.has(name)) {
       this.validateMessages.delete(name);
     }
+    // Notify the field to re-render so async validation results surface in the UI.
+    entity?.onStoreChange();
     return err;
   };
 
-  validateFields = (
+  validateFields = async (
     names = Array.from(this.fieldMap.keys()),
     trigger?: TRIGGER,
-  ) => {
+  ): Promise<ValidateMessage[]> => {
+    // Validate fields in parallel; Promise.all preserves input order so error
+    // ordering stays stable regardless of how long each async validator takes.
+    const results = await Promise.all(
+      names.map((name) => this.validateField(name, trigger)),
+    );
     let err: ValidateMessage[] = [];
-    names.forEach((name) => {
-      const messages = this.validateField(name, trigger);
+    names.forEach((name, index) => {
+      const messages = results[index];
       err = err.concat(messages);
       if (messages.length > 0) {
         this.validateMessages.set(name, messages);
@@ -316,12 +328,16 @@ export class FormStore {
     };
   };
 
-  validateGroups = (force = false): ValidateMessage[] => {
-    let err: ValidateMessage[] = [];
-    this.groupEntities.forEach((entity) => {
-      err = err.concat(entity.validate(force));
-    });
-    return err;
+  validateGroups = async (force = false): Promise<ValidateMessage[]> => {
+    const results = await Promise.all(
+      Array.from(this.groupEntities.values()).map((entity) =>
+        entity.validate(force),
+      ),
+    );
+    return results.reduce(
+      (acc, messages) => acc.concat(messages),
+      [] as ValidateMessage[],
+    );
   };
 
   setCallbacks = (callbacks: Callbacks) => {
@@ -515,10 +531,10 @@ export class FormStore {
     };
   };
 
-  submit = () => {
+  submit = async (): Promise<ValidateMessage[]> => {
     const { onFinish, onFinishFailed } = this.callbacks;
-    const fieldErrors = this.validateFields();
-    const groupErrors = this.validateGroups(true);
+    const fieldErrors = await this.validateFields();
+    const groupErrors = await this.validateGroups(true);
     const allErrors = [...fieldErrors, ...groupErrors];
     if (allErrors.length === 0) {
       onFinish?.(this.getFieldsValue());

package/src/Form/index.en-US.md

@@ -20,6 +20,7 @@ High performance form component with data scope management.
 <code src="./demo/watch.tsx" title="Field Watch" description="useWatch monitors field value changes for conditional rendering"></code>
 <code src="./demo/layout.tsx" title="Layout" description="Different form layouts"></code>
 <code src="./demo/validate.tsx" title="Validation" description="Form validation"></code>
+<code src="./demo/async-validate.tsx" title="Async Validation" description="async validator for server-side checks like uniqueness"></code>
 <code src="./demo/list.tsx" title="Form List" description="Form list field usage"></code>
 <code src="./demo/form-table.tsx" title="Form Table" description="Form table field usage"></code>
 <code src="./demo/dynamic.tsx" title="Dynamic Form" description="Dynamic form items"></code>
@@ -50,16 +51,16 @@ High performance form component with data scope management.
 
 | Property              | Type                                                                                       | Description               |
 | --------------------- | ------------------------------------------------------------------------------------------ | ------------------------- |
-| getFieldValidate      | `(name: Name) => ValidateMessage \| null`                                     | Get field validation      |
+| getFieldValidate      | `(name: Name) => ValidateMessage \| null` | Get field validation (may lag before async validation completes; updates via onStoreChange) |
 | getFieldValue         | `(name: Name) => StoreValue`                                                           | Get field value           |
-| submit                | `() => void`                                                                               | Submit form               |
+| submit                | `() => Promise<ValidateMessage[]>`                                                          | Submit form (async, triggers onFinish only after validation completes) |
 | getFieldsValue        | `() => Values`                                                                             | Get all field values      |
 | setFieldsValue        | `(newStore: Store, trigger?: TRIGGER) => void`                                            | Set field values          |
 | setCallbacks          | `(callbacks: Callbacks) => void`                                                           | Set callbacks             |
 | resetFields           | `(name?: Name[]) => void`                                                              | Reset fields              |
 | clearFields           | `(name?: Name[]) => void`                                                              | Clear fields              |
-| validateField         | `(name: Name, trigger?: 'onChange' \| 'onBlur') => ValidateMessage[]`                 | Validate single field     |
-| validateFields        | `(names?: Name[], trigger?: TRIGGER) => ValidateMessage[]`                              | Validate multiple fields  |
+| validateField         | `(name: Name, trigger?: 'onChange' \| 'onBlur') => Promise<ValidateMessage[]>`                 | Validate single field     |
+| validateFields        | `(names?: Name[], trigger?: TRIGGER) => Promise<ValidateMessage[]>`                              | Validate multiple fields  |
 | getCallbacks          | `() => Callbacks`                                                     | Get callbacks             |
 | registerFieldEntities | `(entity: FieldEntity) => void`                                                            | Register field entities   |
 | initialize            | `({ initialValues, callbacks }: { initialValues?: Store; callbacks?: Callbacks }) => void` | Initialize form           |
@@ -117,7 +118,7 @@ High performance form component with data scope management.
 | maxLength       | `number`        | Maximum length           |
 | regexp          | `RegExp`        | Regular expression       |
 | message         | `string`        | Error message            |
-| validator       | `(value: unknown) => boolean` | Custom validator function |
+| validator       | `(value: unknown) => boolean \| void \| Promise<boolean \| void>` | Custom validator. Supports sync and async: sync `return false`/`throw` fails; async `resolve(false)`/`reject`/`throw` fails. When throwing/rejecting with an Error, `error.message` overrides `message` |
 | validateTrigger | `'onBlur' \| 'onChange' \| 'onSubmit' \| Array<'onBlur' \| 'onChange' \| 'onSubmit'>` | Validation trigger |
 
 ### Types

package/src/Form/index.zh-CN.md

@@ -22,6 +22,7 @@ toc: 'content'
 <code src="./demo/form-table.tsx" title="表单列表" description="Form的列表字段用法"></code>
 <code src="./demo/layout.tsx" title="表单布局" description="不同的表单布局"></code>
 <code src="./demo/validate.tsx" title="表单校验" description="表单校验功能"></code>
+<code src="./demo/async-validate.tsx" title="异步校验" description="async validator 实现服务端唯一性校验等异步场景"></code>
 
 ## API
 
@@ -49,16 +50,16 @@ toc: 'content'
 
 | 属性名                | 类型                                                                                       | 描述                                       |
 | --------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------ |
-| getFieldValidate      | `(name: Name) => ValidateMessage \| null`                                                  | 获取字段验证                               |
+| getFieldValidate      | `(name: Name) => ValidateMessage \| null` | 获取字段验证（异步校验未完成时可能读到旧值，最终会随 onStoreChange 更新） |
 | getFieldValue         | `(name: Name) => StoreValue`                                                               | 获取字段值                                 |
-| submit                | `() => void`                                                                               | 提交表单                                   |
+| submit                | `() => Promise<ValidateMessage[]>`                                                          | 提交表单（异步，校验完成后才触发 onFinish） |
 | getFieldsValue        | `() => Values`                                                                             | 获取所有字段值                             |
 | setFieldsValue        | `(newStore: Store, trigger?: TRIGGER) => void`                                             | 设置字段值                                 |
 | setCallbacks          | `(callbacks: Callbacks) => void`                                                           | 设置回调                                   |
 | resetFields           | `(name?: Name[]) => void`                                                                  | 重置字段                                   |
 | clearFields           | `(name?: Name[]) => void`                                                                  | 清空字段                                   |
-| validateField         | `(name: Name, trigger?: 'onChange' \| 'onBlur') => ValidateMessage[]`                      | 校验单个字段                               |
-| validateFields        | `(names?: Name[], trigger?: TRIGGER) => ValidateMessage[]`                                 | 校验多个字段                               |
+| validateField         | `(name: Name, trigger?: 'onChange' \| 'onBlur') => Promise<ValidateMessage[]>`                      | 校验单个字段                               |
+| validateFields        | `(names?: Name[], trigger?: TRIGGER) => Promise<ValidateMessage[]>`                                 | 校验多个字段                               |
 | getCallbacks          | `() => Callbacks`                                                                          | 获取回调                                   |
 | registerFieldEntities | `(entity: FieldEntity) => void`                                                            | 注册字段实体                               |
 | initialize            | `({ initialValues, callbacks }: { initialValues?: Store; callbacks?: Callbacks }) => void` | 初始化表单                                 |
@@ -116,7 +117,7 @@ toc: 'content'
 | maxLength       | `number`                                                                              | 最大长度       |
 | regexp          | `RegExp`                                                                              | 正则表达式     |
 | message         | `string`                                                                              | 错误信息       |
-| validator       | `(value: unknown) => boolean`                                                         | 自定义校验函数 |
+| validator       | `(value: unknown) => boolean \| void \| Promise<boolean \| void>` | 自定义校验函数，支持同步与异步。同步返回 `false` 或 `throw` 表示失败；异步 `resolve(false)`/`reject`/`throw` 表示失败。`throw`/`reject` 时 `error.message` 覆盖 `message` |
 | validateTrigger | `'onBlur' \| 'onChange' \| 'onSubmit' \| Array<'onBlur' \| 'onChange' \| 'onSubmit'>` | 校验触发时机   |
 
 ### Types

package/src/Form/interface.ts

@@ -113,7 +113,7 @@ export interface FormInstance<Values = any> {
   /**
    * Submit form
    */
-  submit: () => ValidateMessage[];
+  submit: () => Promise<ValidateMessage[]>;
   /**
    * Get all field values
    */
@@ -140,7 +140,7 @@ export interface FormInstance<Values = any> {
   validateField: (
     name: Name,
     trigger?: 'onChange' | 'onBlur',
-  ) => ValidateMessage[];
+  ) => Promise<ValidateMessage[]>;
   /**
    * Get callback functions
    */
@@ -152,7 +152,10 @@ export interface FormInstance<Values = any> {
   /**
    * Validate fields and get error messages
    */
-  validateFields: (names?: Name[], trigger?: TRIGGER) => ValidateMessage[];
+  validateFields: (
+    names?: Name[],
+    trigger?: TRIGGER,
+  ) => Promise<ValidateMessage[]>;
   /**
    * Initialize form - mainly used to set initial values and callbacks
    */
@@ -233,9 +236,12 @@ export type Rule = {
    */
   message?: string;
   /**
-   * Custom validation function, returns true for pass, false or throw for fail
+   * Custom validation function. Supports sync and async:
+   *  - sync:  return true/undefined to pass, return false or throw to fail
+   *  - async: return a Promise (resolve to pass, reject/throw to fail)
+   * When throwing/rejecting with an Error, its message overrides rule.message.
    */
-  validator?: (value: unknown) => boolean;
+  validator?: (value: unknown) => boolean | void | Promise<boolean | void>;
   /**
    * Validation trigger timing
    */
@@ -354,7 +360,7 @@ export type FormListField<T = any> = {
 };
 
 export type FormListOperation = {
-  add: (defaultValue?: any, insertIndex?: number) => void;
+  add: (defaultValue?: any, insertIndex?: number) => void | Promise<void>;
   remove: (index: number | number[]) => void;
   move: (from: number, to: number) => void;
 };
@@ -403,6 +409,6 @@ export type FieldGroupProps = {
 };
 
 export interface GroupEntity {
-  validate: (force: boolean) => ValidateMessage[];
+  validate: (force: boolean) => Promise<ValidateMessage[]>;
   reset: () => void;
 }

package/src/Form/utils/validate.ts

@@ -1,5 +1,4 @@
-// true: 校验通过；false校验未通过
-import { Rule } from '../interface';
+import type { Rule } from '../interface';
 
 function isEmpty(v: unknown) {
   return v === undefined || v === null || v === '' ? true : false;
@@ -60,11 +59,15 @@ function verifyRuleOfRegexp(regexp: RegExp, value: unknown) {
   }
 }
 
-/**
- * @returns validated
- * */
-function verifyMain(rule: Rule, value: any): boolean {
-  const { min, max, minLength, maxLength, regexp, validator } = rule;
+export interface ValidateResult {
+  passed: boolean;
+  // Custom message from a thrown/rejected validator; falls back to rule.message upstream
+  message?: string;
+}
+
+// Check the synchronous built-in rules (min/max/minLength/maxLength/regexp).
+function verifySyncRules(rule: Rule, value: unknown): boolean {
+  const { min, max, minLength, maxLength, regexp } = rule;
 
   if (typeof min !== 'undefined' && !verifyRuleOfMin(min, value)) {
     return false;
@@ -87,18 +90,67 @@ function verifyMain(rule: Rule, value: any): boolean {
   if (regexp instanceof RegExp && !verifyRuleOfRegexp(regexp, value)) {
     return false;
   }
-  if (typeof validator === 'function' && !validator(value)) {
-    return false;
-  }
   return true;
 }
 
-function validate(rule: Rule, value: unknown): boolean {
+/**
+ * Run a custom validator, dispatching between sync and async at runtime.
+ *
+ * Supports all of the following shapes (backwards compatible):
+ *  - sync `return true` / `return undefined` → pass
+ *  - sync `return false`                    → fail (use rule.message)
+ *  - sync `throw new Error(msg)`            → fail (use msg)
+ *  - async `return Promise.resolve()`       → pass
+ *  - async `return Promise.resolve(false)`  → fail (use rule.message)
+ *  - async `throw` / `return Promise.reject(new Error(msg))` → fail (use msg)
+ */
+export async function runValidator(
+  validator: NonNullable<Rule['validator']>,
+  value: unknown,
+): Promise<ValidateResult> {
+  try {
+    const res = validator(value);
+    if (res instanceof Promise) {
+      const resolved = await res;
+      if (resolved === false) {
+        return { passed: false };
+      }
+      return { passed: true };
+    }
+    if (res === false) {
+      return { passed: false };
+    }
+    return { passed: true };
+  } catch (e) {
+    return {
+      passed: false,
+      message: e instanceof Error ? e.message : String(e),
+    };
+  }
+}
+
+/**
+ * Validate a single rule against a value.
+ * Returns { passed, message? }. Sync rules short-circuit; the custom validator
+ * is awaited so async validators are supported.
+ */
+async function validate(
+  rule: Rule,
+  value: unknown,
+): Promise<ValidateResult> {
   if (rule.required && isEmpty(value)) {
-    return false;
+    return { passed: false };
+  }
+
+  if (!verifySyncRules(rule, value)) {
+    return { passed: false };
+  }
+
+  if (typeof rule.validator === 'function') {
+    return runValidator(rule.validator, value);
   }
 
-  return verifyMain(rule, value);
+  return { passed: true };
 }
 
 export default validate;

package/src/Select/demo/basic.tsx

@@ -15,7 +15,7 @@ const options = [
 ];
 
 export default () => {
-  const [value, setValue] = useState('apple');
+  const [value, setValue] = useState('mango');
 
   return (
     <Select