feat: add isValidating state while validate method is running (#4244)

Author: viajes7

.changeset/purple-eggs-ring.md

@@ -0,0 +1,5 @@
+---
+'vee-validate': patch
+---
+
+feat: added isValidating to useForm

docs/src/pages/api/composition-helpers.mdx

@@ -258,6 +258,22 @@ useIsSubmitting.value; // true or false
 
 <CodeTitle level="4">
 
+`useIsValidating(): ComputedRef<boolean>`
+
+</CodeTitle>
+
+Returns a computed ref to the form's `isValidating` state.
+
+```js
+import { useIsValidating } from 'vee-validate';
+
+const isValidating = useIsValidating();
+
+isValidating.value; // true or false
+```
+
+<CodeTitle level="4">
+
 `useSubmitCount(): ComputedRef<number>`
 
 </CodeTitle>

docs/src/pages/api/form.mdx

@@ -167,6 +167,14 @@ Indicates if the submission handler is still running, once it resolves/rejects i
 
 <CodeTitle level="4">
 
+`isValidating: boolean`
+
+</CodeTitle>
+
+Indicates if the validate function is still running, once validate function is done it will be automatically set to `false` again.
+
+<CodeTitle level="4">
+
 `meta: FormMeta`
 
 </CodeTitle>

docs/src/pages/api/use-form.mdx

@@ -187,6 +187,7 @@ type useForm = (opts?: FormOptions) => {
   errorBag: ComputedRef<Partial<Record<string, string[]>>>; // all error messages for each field
   meta: ComputedRef<FormMeta<TValues>>; // aggregate of the field's meta information
   isSubmitting: Ref<boolean>; // if the form submission function is being run
+  isValidating: Ref<boolean>; // if the form validate function is being run
   setFieldValue<T extends keyof TValues>(field: T, value: TValues[T]): void; // Sets a field value
   setFieldError: (field: keyof TValues, message: string | string[] | undefined) => void; // Sets an error message for a field
   setErrors: (fields: FormErrors<TValues>) => void; // Sets error messages for fields
@@ -332,6 +333,20 @@ isSubmitting.value; // true or false
 
 <CodeTitle level="4">
 
+`isValidating: Ref<boolean>`
+
+</CodeTitle>
+
+Indicates if the validate function is still running, once validate function is done it will be automatically set to `false` again.
+
+```js
+const { isValidating } = useForm();
+
+isValidating.value; // true or false
+```
+
+<CodeTitle level="4">
+
 `meta: ComputedRef<FormMeta>`
 
 </CodeTitle>

docs/src/pages/guide/composition-api/api-review.mdx

@@ -61,6 +61,7 @@ Here is a list of the functions available that you can use:
 - `useResetForm` Resets the form to its initial state
 - `useSubmitForm` Creates a submission function that validates and submits the form (even if no `form` element is involved)
 - `useIsSubmitting` If the form is currently submitting
+- `useIsValidating` If the form is currently validating by validate function
 - `useSubmitCount` The number of times the user attempted to submit the form
 - `useFieldValue` Returns a specific fields' current value
 - `useFormValues` Returns the current form field values

packages/vee-validate/src/Form.ts

@@ -12,6 +12,7 @@ type FormSlotProps = UnwrapRef<
     | 'errorBag'
     | 'values'
     | 'isSubmitting'
+    | 'isValidating'
     | 'submitCount'
     | 'validate'
     | 'validateField'
@@ -86,6 +87,7 @@ const FormImpl = defineComponent({
       values,
       meta,
       isSubmitting,
+      isValidating,
       submitCount,
       controlledValues,
       validate,
@@ -153,6 +155,7 @@ const FormImpl = defineComponent({
         errorBag: errorBag.value,
         values,
         isSubmitting: isSubmitting.value,
+        isValidating: isValidating.value,
         submitCount: submitCount.value,
         controlledValues: controlledValues.value,
         validate,

packages/vee-validate/src/devtools.ts

@@ -430,7 +430,7 @@ function buildFieldState(
 }
 
 function buildFormState(form: PrivateFormContext): CustomInspectorState {
-  const { errorBag, meta, values, isSubmitting, submitCount } = form;
+  const { errorBag, meta, values, isSubmitting, isValidating, submitCount } = form;
 
   return {
     'Form state': [
@@ -442,6 +442,10 @@ function buildFormState(form: PrivateFormContext): CustomInspectorState {
         key: 'isSubmitting',
         value: isSubmitting.value,
       },
+      {
+        key: 'isValidating',
+        value: isValidating.value,
+      },
       {
         key: 'touched',
         value: meta.value.touched,

packages/vee-validate/src/index.ts

@@ -41,6 +41,7 @@ export { useIsFieldDirty } from './useIsFieldDirty';
 export { useIsFieldTouched } from './useIsFieldTouched';
 export { useIsFieldValid } from './useIsFieldValid';
 export { useIsSubmitting } from './useIsSubmitting';
+export { useIsValidating } from './useIsValidating';
 export { useValidateField } from './useValidateField';
 export { useIsFormDirty } from './useIsFormDirty';
 export { useIsFormTouched } from './useIsFormTouched';

packages/vee-validate/src/types/devtools.ts

@@ -13,5 +13,6 @@ export interface DevtoolsPluginFormState {
   errors: FormErrors<Record<string, any>>;
   values: Record<string, any>;
   isSubmitting: boolean;
+  isValidating: boolean;
   submitCount: number;
 }

packages/vee-validate/src/types/forms.ts

@@ -231,6 +231,7 @@ export interface PrivateFormContext<TValues extends GenericObject = GenericObjec
   errors: ComputedRef<FormErrors<TValues>>;
   meta: ComputedRef<FormMeta<TValues>>;
   isSubmitting: Ref<boolean>;
+  isValidating: Ref<boolean>;
   keepValuesOnUnmount: MaybeRef<boolean>;
   validateSchema?: (mode: SchemaValidationMode) => Promise<FormValidationResult<TValues, TOutput>>;
   validate(opts?: Partial<ValidationOptions>): Promise<FormValidationResult<TValues, TOutput>>;

packages/vee-validate/src/useForm.ts

@@ -119,6 +119,9 @@ export function useForm<
   // If the form is currently submitting
   const isSubmitting = ref(false);
 
+  // If the form is currently validating
+  const isValidating = ref(false);
+
   // The number of times the user tried to submit the form
   const submitCount = ref(0);
 
@@ -517,6 +520,7 @@ export function useForm<
     submitCount,
     meta,
     isSubmitting,
+    isValidating,
     fieldArrays,
     keepValuesOnUnmount,
     validateSchema: unref(schema) ? validateSchema : undefined,
@@ -659,6 +663,8 @@ export function useForm<
       return formCtx.validateSchema(mode);
     }
 
+    isValidating.value = true;
+
     // No schema, each field is responsible to validate itself
     const validations = await Promise.all(
       pathStates.value.map(state => {
@@ -680,6 +686,8 @@ export function useForm<
       })
     );
 
+    isValidating.value = false;
+
     const results: Partial<FlattenAndSetPathsType<TValues, ValidationResult>> = {};
     const errors: Partial<FlattenAndSetPathsType<TValues, string>> = {};
     for (const validation of validations) {
@@ -748,6 +756,8 @@ export function useForm<
       return { valid: true, results: {}, errors: {} };
     }
 
+    isValidating.value = true;
+
     const formResult =
       isYupValidator(schemaValue) || isTypedSchema(schemaValue)
         ? await validateTypedSchema<TValues, TOutput>(schemaValue, formValues)
@@ -756,6 +766,8 @@ export function useForm<
             bailsMap: fieldBailsMap.value,
           });
 
+    isValidating.value = false;
+
     return formResult;
   }
 
@@ -805,6 +817,7 @@ export function useForm<
         ...meta.value,
         values: formValues,
         isSubmitting: isSubmitting.value,
+        isValidating: isValidating.value,
         submitCount: submitCount.value,
       }),
       refreshInspector,

packages/vee-validate/src/useIsValidating.ts

@@ -0,0 +1,17 @@
+import { computed } from 'vue';
+import { FormContextKey } from './symbols';
+import { injectWithSelf, warn } from './utils';
+
+/**
+ * If the form is validating or not
+ */
+export function useIsValidating() {
+  const form = injectWithSelf(FormContextKey);
+  if (!form) {
+    warn('No vee-validate <Form /> or `useForm` was detected in the component tree');
+  }
+
+  return computed(() => {
+    return form?.isValidating.value ?? false;
+  });
+}

packages/vee-validate/tests/Form.spec.ts

@@ -1,4 +1,4 @@
-import { defineRule, useField, Form } from '@/vee-validate';
+import { defineRule, useField, Form, Field, useIsValidating } from '@/vee-validate';
 import { mountWithHoc, setValue, setChecked, dispatchEvent, flushPromises } from './helpers';
 import * as yup from 'yup';
 import { computed, defineComponent, onErrorCaptured, reactive, ref, Ref } from 'vue';
@@ -1356,6 +1356,43 @@ describe('<Form />', () => {
     expect(submitting.textContent).toBe('false');
   });
 
+  test('isValidating state', async () => {
+    const spy = vi.fn((isValidating: boolean) => isValidating);
+
+    const Input = defineComponent({
+      components: {
+        Field,
+      },
+      template: `<Field name="field" />`,
+      setup() {
+        const isValidating = useIsValidating();
+
+        useField('field', () => {
+          spy(isValidating.value);
+          return true;
+        });
+      },
+    });
+    const wrapper = mountWithHoc({
+      components: {
+        Input,
+      },
+      template: `
+      <VForm v-slot="{ validate }">
+        <Input />
+        <button @click="validate">Validate</button>
+      </VForm>
+    `,
+    });
+
+    await flushPromises();
+    const button = wrapper.$el.querySelector('button');
+    button.click();
+
+    await flushPromises();
+    expect(spy).toHaveLastReturnedWith(true);
+  });
+
   test('aggregated meta reactivity', async () => {
     const wrapper = mountWithHoc({
       template: `

packages/vee-validate/tests/useIsValidating.spec.ts

@@ -0,0 +1,67 @@
+import { useForm, useIsValidating } from '@/vee-validate';
+import { mountWithHoc, flushPromises } from './helpers';
+import { expect } from 'vitest';
+import * as yup from 'yup';
+
+describe('useIsValidating()', () => {
+  test('indicates if a form is validating', async () => {
+    const spy = vi.fn((isValidating: boolean) => isValidating);
+
+    mountWithHoc({
+      setup() {
+        const { validate } = useForm({
+          validationSchema: {
+            name: yup.string().test(() => {
+              spy(isValidating.value);
+              return true;
+            }),
+          },
+        });
+
+        const isValidating = useIsValidating();
+
+        return {
+          validate,
+        };
+      },
+      template: `
+      <button @click="validate">Submit</button>
+    `,
+    });
+
+    await flushPromises();
+    // triggered by validateObjectSchema method
+    expect(spy).toHaveBeenCalledTimes(1);
+    const button = document.querySelector('button');
+    button?.click();
+
+    await flushPromises();
+    // triggered by formCtx validate method
+    expect(spy).toHaveBeenCalledTimes(2);
+    expect(spy).toHaveLastReturnedWith(true);
+  });
+
+  test('returns false and warns if form is not found', async () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {
+      // NOOP
+    });
+    mountWithHoc({
+      setup() {
+        const isValidating = useIsValidating();
+
+        return {
+          isValidating,
+        };
+      },
+      template: `
+      <span>{{ isValidating.toString() }}</span>
+    `,
+    });
+
+    await flushPromises();
+    const validatingText = document.querySelector('span');
+    expect(validatingText?.textContent).toBe('false');
+    expect(console.warn).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});