feat(core): rename onError to onInvalid (#9)

* feat(core): support `onInvalid` to instead of `onError`

* docs: update dcoument

* docs: update dcoument

* test: add test for `onInvalid()`

Author: Mini-ghost

docs/api/use-form.md

@@ -230,6 +230,10 @@ This is your form submission handler, witch will pass your form's `values`. But
 If `onSubmit()` function is synchronous, you need to call `setSubmitting(false)` yourself.
 :::
 
+### onInvalid
+
+This is your invalid handler, called when the form is submitted with invalid values.
+
 ## Returns
 
 ### values

packages/core/src/composables/useForm.ts

@@ -57,8 +57,9 @@ export interface UseFormOptions<Values extends FormValues> {
   reValidateMode?: ValidateMode;
   validateOnMounted?: boolean;
   onSubmit: (values: Values, helper: FormSubmitHelper) => void | Promise<any>;
+  onInvalid?: (errors: FormErrors<Values>) => void;
   /**
-   * @deprecated Will be removed in a major release. Please use `watch(errors, callback)` instead.
+   * @deprecated Will be removed in a major release. Please use `onInvalid()` instead.
    */
   onError?: (errors: FormErrors<Values>) => void;
   validate?: (values: Values) => void | object | Promise<FormErrors<Values>>;
@@ -199,6 +200,7 @@ export function useForm<Values extends FormValues = FormValues>(
     reValidateMode = 'change',
     onSubmit,
     onError,
+    onInvalid,
   } = options;
 
   let initialValues = deepClone(options.initialValues);
@@ -511,6 +513,7 @@ export function useForm<Values extends FormValues = FormValues>(
           });
       } else {
         dispatch({ type: ACTION_TYPE.SUBMIT_FAILURE });
+        onInvalid?.(errors);
         onError?.(errors);
       }
     });

packages/core/tests/composables/useForm.test.ts

@@ -785,6 +785,8 @@ describe('useForm', () => {
     });
 
     await wrapper.find('button[type="submit"]').trigger('click');
+    await sleep();
+
     expect(onSubmit).toHaveBeenCalledTimes(0);
   });
 
@@ -949,6 +951,88 @@ describe('useForm', () => {
     expect(wrapper.find('span').text()).toBe('false');
   });
 
+  it('when onInvalid with validation pass', async () => {
+    const onInvalid = vi.fn();
+
+    const Comp = defineComponent({
+      setup() {
+        const { handleSubmit } = useForm({
+          initialValues: {
+            name: '',
+          },
+          validate() {
+            return undefined;
+          },
+          onSubmit: noop,
+          onInvalid,
+        });
+
+        return {
+          handleSubmit,
+        };
+      },
+
+      template: `
+        <form @submit="handleSubmit">
+          <button type="submit">Submit</button>
+        </form>
+      `,
+    });
+
+    document.body.innerHTML = `<div id="app"></div>`;
+    const wrapper = mount(Comp, {
+      attachTo: '#app',
+    });
+
+    await wrapper.find('button[type="submit"]').trigger('click');
+    await sleep();
+
+    expect(onInvalid).toHaveBeenCalledTimes(0);
+  });
+
+  it('when onInvalid with validation error', async () => {
+    const onInvalid = vi.fn();
+    const errors = {
+      name: 'name is required',
+    };
+
+    const Comp = defineComponent({
+      setup() {
+        const { handleSubmit } = useForm({
+          initialValues: {
+            name: '',
+          },
+          validate() {
+            return errors;
+          },
+          onSubmit: noop,
+          onInvalid,
+        });
+
+        return {
+          handleSubmit,
+        };
+      },
+
+      template: `
+        <form @submit="handleSubmit">
+          <button type="submit">Submit</button>
+        </form>
+      `,
+    });
+
+    document.body.innerHTML = `<div id="app"></div>`;
+    const wrapper = mount(Comp, {
+      attachTo: '#app',
+    });
+
+    await wrapper.find('button[type="submit"]').trigger('click');
+    await sleep();
+
+    expect(onInvalid).toHaveBeenCalledTimes(1);
+    expect(onInvalid).toHaveBeenCalledWith(errors);
+  });
+
   it('when invoke handleReset', async () => {
     const Comp = defineComponent({
       setup() {