Clear functions documented

Author: Daniel Requejo

docs/api/use-form-handler/clear-error.md

@@ -1 +1,96 @@
-# clearError
+# clearError: <font size="3">ClearError</font>
+
+Clears all the errors from the form or the error from a field programmatically.
+
+## Demo
+
+Coming soon...
+## Usage
+
+### Validating/Invalidating the form without a field scoped validation
+
+```vue
+<template>
+    <form>
+        <input type="text" v-bind="register('name')" />
+        <input type="text" v-bind="register('email')" />
+        <input type="text" v-bind="register('password')" />
+        <input type="text" v-bind="register('password_confirmation')" />
+        <button type="submit">Submit</button>
+    </form>
+</template>
+<script setup lang="ts" >
+import { useFormHandler, Interceptor } from '../src/index'
+
+const sleep = (milliseconds: number) => {
+    return new Promise(resolve => setTimeout(resolve, milliseconds))
+}
+
+//validate your fields here
+const validateFieldGroup = async () => {
+    await sleep(1000)
+    return Math.random() < 0.5;
+}
+
+const interceptor: Interceptor = async ({ name, setError, clearError }) => {
+    if (['name', 'email'].includes(name)) {
+        await validateUser()
+            ? clearError(name)
+            : setError('user', 'User already exists')
+    }
+    return true
+}
+
+const { register } = useFormHandler({ interceptor })
+</script>
+```
+
+Notice how we use the combination of [setError](/api/use-form-handler/set-error) and `clearError` in order to invalidate the form when we have some fields that need to be validated together and the error is not scoped to one single field but to the whole field group.
+
+### Clearing the errors of a form after triggering validation/ submitting on demand
+
+```vue
+<template>
+    <form @submit.prevent="handleSubmit(successFn, errorFn)">
+        <input type="text" v-bind="register('name', {
+            required: true
+        })" />
+        <p v-if="formState.errors.name"> {{ formState.errors.name }} </p>
+        <input type="text" v-bind="register('email', {
+            required: true
+        })" />
+        <p v-if="formState.errors.email"> {{ formState.errors.email }} </p>
+        <input type="text" v-bind="register('summary')">
+        <button type="submit">Submit</button>
+    </form>
+</template>
+<script setup lang="ts" >
+import { useFormHandler } from '../src/index'
+import { watch } from 'vue'
+
+let hasErrorsAfterSubmit = false;
+const successFn = (form: any) => { console.log({ form }) }
+const errorFn = () => { hasErrorsAfterSubmit = true }
+
+
+const { register, handleSubmit, values, clearError, formState } = useFormHandler()
+
+watch(
+    () => values,
+    () => {
+        if (hasErrorsAfterSubmit) {
+            clearError();
+            hasErrorsAfterSubmit = false
+        }
+    },
+    { deep: true })
+</script>
+```
+
+## Type Declarations
+
+```ts
+export type ClearError = (
+    name?: string
+) => void
+```

docs/api/use-form-handler/clear-field.md

@@ -1 +1,68 @@
-# clearField
+# clearField: <font size="3">ClearField</font>
+
+Clears a field, this means that the field is set to it's default value or to the fallback value.
+This will also trigger a validation for the field if existing.
+
+## Demo
+
+Coming soon...
+
+## Usage
+
+### Clear a field conditioned by another field
+
+```vue
+<template>
+    <select v-bind="register('continent')" placeholder="Choose your country">
+        <option disabled value=null>Choose your continent</option>
+        <option value="AM">America</option>
+        <option value="AS">Asia</option>
+        <option value="EU">Europe</option>
+    </select>
+    <select v-bind="register('country')" placeholder="Choose your country">
+        <option disabled value=null>Choose your country</option>
+        <option value="CAN">Canada</option>
+        <option value="USA">United States</option>
+        <option value="JAP">Japan</option>
+        <option value="CHN">China</option>
+        <option value="ESP">Spain</option>
+        <option value="DEU">Germany</option>
+    </select>
+</template>
+<script setup lang="ts">
+import { useFormHandler } from 'vue-form-handler'
+
+const interceptor = ({ name, clearField }) => {
+    if (name === 'continent') {
+        clearField('country')
+    }
+    return true
+}
+
+const { register } = useFormHandler({
+    interceptor
+})
+</script>
+```
+
+### Allowing the field to emit a 'clear' event or to have a button that clears a field
+
+```vue
+<template>
+    <input type="text" v-bind="register('clearableField')">
+    <button @click="clearField('clearableField')">X</button>
+</template>
+<script setup lang="ts" >
+import { useFormHandler } from '../src/index'
+
+const { register, clearField } = useFormHandler()
+</script>
+```
+
+## Type Declarations
+
+```ts
+export type ClearField = (
+    name: string
+) => Promise<void>
+```

src/test/handler.test.ts

@@ -21,7 +21,8 @@ describe('Form handler testing', () => {
         expect(formState.isDirty).toBeTruthy()
     })
     it('Clearing a field programmatically', async () => {
-        const { values, setValue, formState, clearField } = useFormHandler();
+        const { register, values, setValue, formState, clearField } = useFormHandler();
+        register('field')
         await setValue('field', 'oneTwoThree');
         expect(values.field).toBe('oneTwoThree')
         expect(formState.isDirty).toBeTruthy()
@@ -30,9 +31,10 @@ describe('Form handler testing', () => {
         expect(formState.isDirty).toBeFalsy()
     })
     it('Clearing an initialized field leaves it dirty', async () => {
-        const { values, formState, clearField } = useFormHandler({
+        const { register, values, formState, clearField } = useFormHandler({
             initialValues: { field: 'value' }
         });
+        register('field')
         expect(values.field).toBe('value')
         expect(formState.isDirty).toBeFalsy()
         await clearField('field');

src/useFormHandler.ts

@@ -177,21 +177,25 @@ const useFormHandler: FormHandler = ({
 
   const handleBlur: HandleBlur = (name) => {
     setTouched(name, true)
-    if (validationMode === 'onBlur' || validationMode === 'always') {
+    if (['always', 'onBlur'].includes(validationMode)) {
       triggerValidation(name)
     }
   }
 
   const handleChange: HandleChange = async (name, value = DEFAULT_FIELD_VALUE) => {
     await setValue(name, value)
     setTouched(name, true)
-    if (validationMode === 'onChange' || validationMode === 'always') {
+    if (['always', 'onChange'].includes(validationMode)) {
       triggerValidation(name)
     }
   }
 
   const clearField: ClearField = async (name) => {
-    await setValue(name, _getDefault(name))
+    const defaultValue: any = _getDefault(name);
+    if (defaultValue !== values[name]) {
+      await setValue(name, defaultValue)
+      await triggerValidation(name)
+    }
   }
 
   const unregister = (name: string) => {