feat: touch all fields on submit (#3278)

docs/content/guide/components/handling-forms.md

@@ -424,6 +424,31 @@ export default {
 
 Note that setting any field's value using this way will trigger validation
 
+## Submission Behavior
+
+vee-validate does the following when you submit a form rendered by `<Form />` or when calling either `handleSubmit` or `submitForm`:
+
+### Before validation stage
+
+- Sets all fields `touched` meta to `true`
+- Sets `isSubmitting` form state to `true`
+- Increments the `submitCount` form state by `1`
+
+### Validation stage
+
+- Sets form and individual fields meta `pending` to `true` to indicate validation is in progress
+- Runs the validation function/schema/rule against the current form values asynchronously
+- Checks for any errors in the validation result
+  - If there are errors then it will skip the next stage and update the validation state (meta, errors) for the form and fields
+  - If there aren't any errors then it will set the `pending` meta flag to `false` and proceed to the next stage
+
+### After validation stage
+
+- Calls the `@submit` handler you specified, or calls the `handleSubmit` callback you provided.
+- After the callbacks in either method finish (it will wait if the result is asynchronous), then it will set `isSubmitting` to `false`
+
+Note that there isn't a need to have `isSubmitting` set back to false if you've used `submitForm`, as this submission method will perform a full-page refresh (native forms behavior).
+
 ## Handling Resets
 
 vee-validate also handles form resets in a similar way to submissions. When resetting the form, all fields' errors and meta flags will be reset to their original state, including the fields' values.

docs/content/guide/composition-api/handling-forms.md

@@ -233,6 +233,31 @@ export default {
 </script>
 ```
 
+## Submission Behavior
+
+vee-validate does the following when calling submission handlers created by `handleSubmit` or when calling `submitForm` as a result of the user submitting the form.
+
+### Before validation stage
+
+- Sets all fields `touched` meta to `true`
+- Sets `isSubmitting` form state to `true`
+- Increments the `submitCount` form state by `1`
+
+### Validation stage
+
+- Sets form and individual fields meta `pending` to `true` to indicate validation is in progress
+- Runs the validation function/schema/rule against the current form values asynchronously
+- Checks for any errors in the validation result
+  - If there are errors then it will skip the next stage and update the validation state (meta, errors) for the form and fields
+  - If there aren't any errors then it will set the `pending` meta flag to `false` and proceed to the next stage
+
+### After validation stage
+
+- Calls the `handleSubmit` handler you passed
+- After the callback finishes (it will wait if the result is asynchronous), then it will set `isSubmitting` to `false`
+
+Note that there isn't a need to have `isSubmitting` set back to false if you've used `submitForm`, as this submission method will perform a full-page refresh (native forms behavior).
+
 ## Handling Resets
 
 vee-validate also handles form resets in a similar way to submissions. When resetting the form, all fields' errors and meta flags will be reset to their original state, including the fields' values.

packages/vee-validate/src/useForm.ts

@@ -345,6 +345,15 @@ export function useForm<TValues extends Record<string, any> = Record<string, any
         e.stopPropagation();
       }
 
+      // Touch all fields
+      setTouched(
+        keysOf(fieldsById.value).reduce((acc, field) => {
+          acc[field] = true;
+
+          return acc;
+        }, {} as Record<keyof TValues, boolean>)
+      );
+
       isSubmitting.value = true;
       submitCount.value++;
       return validate()

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

@@ -1800,4 +1800,36 @@ describe('<Form />', () => {
     await flushPromises();
     expect(document.querySelector('span')?.textContent).toBe('');
   });
+
+  test('submitting forms should touch fields', async () => {
+    const wrapper = mountWithHoc({
+      setup() {
+        return {
+          onSubmit: jest.fn(),
+        };
+      },
+      template: `
+      <VForm @submit="onSubmit" v-slot="{ meta }">
+        <Field id="email" name="email" as="input" rules="required" />
+        <Field id="password" name="password" as="input" rules="required" v-slot="fieldProps">
+          <input v-bind="fieldProps.field" />
+          <span id="fieldMeta">{{ fieldProps.meta.touched ? 'touched' : 'untouched' }}</span>
+        </Field>
+
+        <span id="meta">{{ meta.touched ? 'touched' : 'untouched' }}</span>
+        <button type="submit">Submit</button> 
+      </VForm>
+    `,
+    });
+
+    await flushPromises();
+    const formMeta = wrapper.$el.querySelector('#meta');
+    const fieldMeta = wrapper.$el.querySelector('#fieldMeta');
+    expect(formMeta.textContent).toBe('untouched');
+    expect(fieldMeta.textContent).toBe('untouched');
+    wrapper.$el.querySelector('button').click();
+    await flushPromises();
+    expect(formMeta.textContent).toBe('touched');
+    expect(fieldMeta.textContent).toBe('touched');
+  });
 });