feat: new reset API

Author: logaretm

packages/vee-validate/src/types.ts

@@ -30,6 +30,13 @@ export type SubmitEvent = Event & { target: HTMLFormElement };
 
 export type GenericValidateFunction = (value: any) => boolean | string | Promise<boolean | string>;
 
+export interface FormState<TValues> {
+  values: TValues;
+  errors: Partial<Record<keyof TValues, string | undefined>>;
+  dirty: Partial<Record<keyof TValues, boolean>>;
+  touched: Partial<Record<keyof TValues, boolean>>;
+}
+
 export interface FormContext<TValues extends Record<string, any> = Record<string, any>> {
   register(field: any): void;
   unregister(field: any): void;
@@ -45,7 +52,7 @@ export interface FormContext<TValues extends Record<string, any> = Record<string
   setTouched: (fields: Partial<Record<keyof TValues, boolean>>) => void;
   setFieldDirty: (field: keyof TValues, isDirty: boolean) => void;
   setDirty: (fields: Partial<Record<keyof TValues, boolean>>) => void;
-  reset: () => void;
+  reset: (state?: Partial<FormState<TValues>>) => void;
 }
 
 type SubmissionContext<TValues extends Record<string, any> = Record<string, any>> = {

packages/vee-validate/src/useField.ts

@@ -12,6 +12,7 @@ import {
   getCurrentInstance,
   unref,
   InjectionKey,
+  WatchStopHandle,
 } from 'vue';
 import { validate as validateValue } from './validate';
 import { FormContext, ValidationResult, MaybeReactive, GenericValidateFunction, FieldMeta } from './types';
@@ -52,7 +53,7 @@ export function useField(name: MaybeReactive<string>, rules: RuleExpression, opt
   );
 
   const form = injectWithSelf(FormSymbol);
-  const { meta, errors, handleBlur, handleInput, reset, setValidationState, value, checked } = useValidationState({
+  const { meta, errors, handleBlur, handleInput, resetField, setValidationState, value, checked } = useValidationState({
     name,
     // make sure to unref initial value because of possible refs passed in
     initValue: unref(initialValue),
@@ -113,6 +114,23 @@ export function useField(name: MaybeReactive<string>, rules: RuleExpression, opt
     meta.dirty = isDirty;
   }
 
+  let unwatchValue: WatchStopHandle;
+  function watchValue() {
+    if (validateOnValueUpdate) {
+      unwatchValue = watch(value, validate, {
+        deep: true,
+      });
+    }
+  }
+
+  watchValue();
+
+  function reset() {
+    unwatchValue?.();
+    resetField();
+    watchValue();
+  }
+
   const field = {
     fid,
     name,
@@ -134,12 +152,6 @@ export function useField(name: MaybeReactive<string>, rules: RuleExpression, opt
     setDirty,
   };
 
-  if (validateOnValueUpdate) {
-    watch(value, validate, {
-      deep: true,
-    });
-  }
-
   if (isRef(rules) && typeof unref(rules) !== 'function') {
     watch(rules, validate, {
       deep: true,
@@ -285,17 +297,17 @@ function useValidationState({
   }
 
   // Resets the validation state
-  const reset = () => {
+  function resetField() {
     value.value = getFromPath(unref(formInitialValues), unref(name)) ?? initValue;
     errors.value = [];
     resetFlags();
-  };
+  }
 
   return {
     meta,
     errors,
     setValidationState,
-    reset,
+    resetField,
     handleBlur,
     handleInput,
     value,

packages/vee-validate/src/useForm.ts

@@ -9,6 +9,7 @@ import {
   SubmitEvent,
   ValidationResult,
   MaybeReactive,
+  FormState,
 } from './types';
 import { getFromPath, isYupValidator, keysOf, setInPath, unsetPath } from './utils';
 import { FormErrorsSymbol, FormInitialValues, FormSymbol } from './symbols';
@@ -85,7 +86,11 @@ export function useForm<TValues extends Record<string, any> = Record<string, any
   });
 
   // initial form values
-  const { initialValues } = useFormInitialValues<TValues>(fieldsById, formValues, opts?.initialValues);
+  const { initialValues, setInitialValues } = useFormInitialValues<TValues>(
+    fieldsById,
+    formValues,
+    opts?.initialValues
+  );
 
   // form meta aggregations
   const meta = useFormMeta(fields, initialValues);
@@ -213,8 +218,25 @@ export function useForm<TValues extends Record<string, any> = Record<string, any
   /**
    * Resets all fields
    */
-  const handleReset = () => {
+  const reset = (state?: Partial<FormState<TValues>>) => {
+    // set initial values if provided
+    if (state?.values) {
+      setInitialValues(state.values);
+    }
+
+    // Reset all fields state
     fields.value.forEach((f: any) => f.reset());
+
+    // set explicit state afterwards
+    if (state?.dirty) {
+      setDirty(state.dirty);
+    }
+    if (state?.touched) {
+      setTouched(state.touched);
+    }
+    if (state?.errors) {
+      setErrors(state.errors);
+    }
   };
 
   function registerField(field: FieldComposite) {
@@ -294,7 +316,7 @@ export function useForm<TValues extends Record<string, any> = Record<string, any
     setTouched,
     setFieldDirty,
     setDirty,
-    reset: handleReset,
+    reset,
   };
 
   const validate = async () => {
@@ -375,7 +397,6 @@ export function useForm<TValues extends Record<string, any> = Record<string, any
   });
 
   // Provide injections
-  provide(FormInitialValues, initialValues);
   provide(FormSymbol, formCtx as FormContext);
   provide(FormErrorsSymbol, errors);
 
@@ -385,7 +406,8 @@ export function useForm<TValues extends Record<string, any> = Record<string, any
     values: formValues,
     validate,
     isSubmitting,
-    handleReset,
+    handleReset: () => reset(),
+    resetForm: reset,
     handleSubmit,
     submitForm,
     setFieldError,
@@ -482,43 +504,59 @@ async function validateYupSchema<TValues>(
 /**
  * Manages the initial values prop
  */
-function useFormInitialValues<TValues>(
+function useFormInitialValues<TValues extends Record<string, any>>(
   fields: Ref<Record<keyof TValues, any>>,
   formValues: TValues,
   providedValues?: MaybeReactive<TValues>
 ) {
-  const initialValues = computed<TValues>(() => {
-    if (isRef(providedValues)) {
-      return providedValues.value;
-    }
-
-    return providedValues || ({} as TValues);
+  const initialValues = ref<TValues>((unref(providedValues) as TValues) || ({} as TValues));
+  // acts as a read only proxy of the initial values object
+  const computedInitials = computed<TValues>(() => {
+    return initialValues.value as TValues;
   });
 
-  // Watch initial values for changes, and update the pristine (non-dirty and non-touched fields)
-  // we exclude dirty and untouched fields because it's unlikely you want to change the form values using initial values
-  // we mostly watch them for API population or newly inserted fields
-  watch(
-    initialValues,
-    value => {
-      const isSafeToUpdate = (f: any) => f.meta.dirty || f.meta.touched;
-      keysOf(fields.value).forEach(fieldPath => {
-        const field = fields.value[fieldPath];
-        const isFieldDirty = Array.isArray(field) ? field.some(isSafeToUpdate) : isSafeToUpdate(field);
-        if (isFieldDirty) {
-          return;
-        }
+  function setInitialValues(values: Partial<TValues>, updateFields = false) {
+    initialValues.value = {
+      ...initialValues.value,
+      ...values,
+    };
 
-        const newValue = getFromPath(value, fieldPath as string);
-        setInPath(formValues, fieldPath as string, newValue);
-      });
-    },
-    {
-      deep: true,
+    if (!updateFields) {
+      return;
     }
-  );
+
+    // update the pristine (non-dirty and non-touched fields)
+    // we exclude dirty and untouched fields because it's unlikely you want to change the form values using initial values
+    // we mostly watch them for API population or newly inserted fields
+    const isSafeToUpdate = (f: any) => f.meta.dirty || f.meta.touched;
+    keysOf(fields.value).forEach(fieldPath => {
+      const field = fields.value[fieldPath];
+      const isFieldDirty = Array.isArray(field) ? field.some(isSafeToUpdate) : isSafeToUpdate(field);
+      if (isFieldDirty) {
+        return;
+      }
+
+      const newValue = getFromPath(initialValues.value, fieldPath as string);
+      setInPath(formValues, fieldPath as string, newValue);
+    });
+  }
+
+  if (isRef(providedValues)) {
+    watch(
+      providedValues,
+      value => {
+        setInitialValues(value, true);
+      },
+      {
+        deep: true,
+      }
+    );
+  }
+
+  provide(FormInitialValues, computedInitials);
 
   return {
-    initialValues,
+    initialValues: computedInitials,
+    setInitialValues,
   };
 }

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

@@ -111,16 +111,23 @@ describe('<Form />', () => {
     });
 
     const error = wrapper.$el.querySelector('#error');
+    const input = wrapper.$el.querySelector('input');
+
     expect(error.textContent).toBe('');
 
     wrapper.$el.querySelector('#submit').click();
     await flushPromises();
 
     expect(error.textContent).toBe(REQUIRED_MESSAGE);
 
+    setValue(input, 'value');
+    await flushPromises();
     wrapper.$el.querySelector('#reset').click();
     await flushPromises();
 
+    // value was reset
+    expect(input.value).toBe('');
+    // errors were cleared
     expect(error.textContent).toBe('');
     expect(isReset).toBe(true);
   });