📜 Base handler, component docs & code alignment

Author: Daniel Requejo

docs/.vitepress/config.cts

@@ -51,7 +51,8 @@ export default defineConfig({
       {
         text: 'API Reference', items: [
           {
-            text: 'useFormHandler', link: '/api/use-form-handler/index', items: [
+            text: 'useFormHandler', link: '/api/use-form-handler/',
+            items: [
               { text: 'clearError', link: '/api/use-form-handler/clear-error' },
               { text: 'clearField', link: '/api/use-form-handler/clear-field' },
               { text: 'formState', link: '/api/use-form-handler/form-state' },

docs/api/form-handler.md

@@ -1 +1,34 @@
-# \<FormHandler/>
+# \<FormHandler/>: <font size="3">Component</font>
+
+The `FormHandler` component is an utility for people that are still using the options API or, that for some reason want to do the handling on the template side. 
+
+::: tip
+It is highly recommend that you use the `useFormHandler` composable if possible, since it is the intended way of making use of this package and gives you more control over the form.
+:::
+## How it works
+
+You pass the same props as you'd be passing to the composable but to a component on the template, and the component will enable you a [scoped slot](https://vuejs.org/guide/components/slots.html#scoped-slots) with the return of `useFormHandler`.
+
+As you can imagine, the `FormHandler` composable and `useFormHandler` share the same API but differ in the usage.
+
+## Example: 
+
+```vue
+<template @submit.prevent="handleSubmit(successFn)">
+    <FormHandler>
+        <template v-slot="{register, handleSubmit}">
+            <form @submit.prevent="handleSubmit(successFn)">
+                <input v-bind="register('firstName')">
+                <input v-bind="register('lastName')">
+            </form>
+        </template>
+    </FormHandler>
+</template>
+<script setup lang="ts">
+    import { FormHandler } from 'vue-form-handler'
+    
+    const successFn = (form:Record<string,any>) => {
+        console.log({form})
+    }
+</script>
+```

docs/api/use-form-handler/index.md

@@ -1 +1,160 @@
-# useFormHandler
+# useFormHandler: <font size=3>FormHandler</font>
+
+`useFormHandler` is our composable to handle forms, it takes one object as **optional** argument and returns various objects and methods that will allow us to handle our forms.
+
+## Props
+
+### initialValues: <font size=2>Record<string,any></font>
+
+::: warning
+Changing the initialValues will trigger a form reset, this means the formState and the values will return to its initial state.
+:::
+
+Values which we use to initialize the form, this is useful when we get an initial value state for the form from an external call.
+
+#### Example
+```vue
+<template>
+    <input v-bind="register('firstName')"> // Should initially be 'John'
+    <input v-bind="register('lastName')"> // Should initially be 'Doe'
+    <pre>{{values}}</pre> // Should show the initialized values
+</template>
+<script setup lang="ts">
+    import { useFormHandler } from 'vue-form-handler'
+
+    const { register, values } = useFormHandler({
+        initialValues: {
+            firstName: 'John',
+            lastName: 'Doe'
+        }
+    })
+</script>
+```
+
+### interceptor: <font size=2>Interceptor</font>
+
+Function that allows us to intercept any value assignment, accept or deny it and perform operations before and after the assignment happens.
+
+#### Params
+
+The interceptor will be called passing an object as a parameter with the following:
+
+| attribute | type   | description                                |
+|-----------|--------|--------------------------------------------|
+| name      | string    | Name of the field that is about to be set  |
+| value     | any    | Value of the field that is about to be set |
+| clearError | ClearError | [API - clearError](/api/use-form-handler/clear-error) |
+| clearField | ClearField | [API - clearField](/api/use-form-handler/clear-field) |
+| formState | FormState | [API - formState](/api/use-form-handler/form-state) |
+| modifiedValues | ModifiedValues | [API - modifiedValues](/api/use-form-handler/modified-values) |
+| resetField | ResetField | [API - resetField](/api/use-form-handler/reset-field) |
+| resetForm | ResetForm | [API - resetForm](/api/use-form-handler/reset-form) |
+| setError | SetError | [API - setError](/api/use-form-handler/set-error) |
+| setValue | SetValue | [API - setValue](/api/use-form-handler/set-value) |
+| triggerValidation | TriggerValidation | [API - triggerValidation](/api/use-form-handler/trigger-validation) |
+| values    | Record<string,any> | [API - values](/api/use-form-handler/values) |
+
+::: info
+As you can see, the interceptor is provided with everything the handler does provide but in a separate context.
+:::
+
+#### Expected return
+
+The interceptor expects a type of `boolean` or a `Promise<boolean>`,
+return true to proceed setting the value and false if the value should not be set.
+
+#### Example
+
+```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>
+```
+
+### validate: <font size=2>FormValidation</font>
+
+Use this function in the case you'd rather perform a custom/different validation when submitting your form
+
+#### Example
+
+```vue
+<template @submit.prevent="handleSubmit(successFn)">
+    <form>
+        <input v-bind="register('firstName')">
+        <input v-bind="register('lastName')">
+        <input type="number" v-bind="register('age')">
+        <input type="submit">
+    </form>
+</template>
+<script setup lang="ts">
+    import { useFormHandler } from 'vue-form-handler'
+    
+    const validation = (values) => values.age && Number(values.age)>=18
+    const successFn = (form:Record<string,any>) => {
+        console.log({form})
+    }
+
+    const { register, handleSubmit } = useFormHandler({
+        validation
+    })
+</script>
+```
+
+### validationMode: <font size="2">'onChange' | 'onBlur' | 'onSubmit' | 'always'</font>
+
+This option allows you to configure the validation mode or strategy the handler will follow.
+
+| name | type   | description                                |
+|-----------|--------|--------------------------------------------|
+| onChange      | string    | Validation will trigger on the change event with each input, and lead to multiple re-renders.  |
+| onBlur     | string    | Validation will trigger on the blur event. |
+| onSubmit    | string | 	Validation will trigger on the submit event. |
+| always    | string | 	Validation will trigger on change and blur events.  |
+
+::: warning
+Using the `always` validationMode will have a more significant impact on performance.
+:::
+
+## Return
+
+- [clearError](/api/use-form-handler/clear-error)
+- [clearField](/api/use-form-handler/clear-field)
+- [formState](/api/use-form-handler/form-state)
+- [handleSubmit](/api/use-form-handler/handle-submit)
+- [modifiedValues](/api/use-form-handler/modified-values)
+- [register](/api/use-form-handler/register)
+- [resetField](/api/use-form-handler/reset-field)
+- [resetForm](/api/use-form-handler/reset-form)
+- [setError](/api/use-form-handler/set-error)
+- [setValue](/api/use-form-handler/set-value)
+- [triggerValidation](/api/use-form-handler/trigger-validation)
+- [unregister](/api/use-form-handler/unregister)
+- [values](/api/use-form-handler/values)

docs/tutorial.md

@@ -129,23 +129,23 @@ Our current form works but it's not complete at all, we might want to add valida
             required: true,
             pattern: emailRegExp
         })" />
-        <p class="error" v-show="formState.errors.email">
-            {{formState.errors.email}}
-        </p>
+    <p class="error" v-show="formState.errors.email">
+        {{formState.errors.email}}
+    </p>
 		<input type="password" v-bind="register('password', {
             required: true,
             pattern: passwordRegExp
         })" />
-        <p class="error" v-show="formState.errors.password">
-            {{formState.errors.password}}
-        </p>
-        <input type="password" v-bind="register('confirmPassword', {
+    <p class="error" v-show="formState.errors.password">
+        {{formState.errors.password}}
+    </p>
+    <input type="password" v-bind="register('confirmPassword', {
             required: true,
             pattern: passwordRegExp
         })" />
-        <p class="error" v-show="formState.errors.confirmPassword">
-            {{formState.errors.confirmPassword}}
-        </p>
+    <p class="error" v-show="formState.errors.confirmPassword">
+        {{formState.errors.confirmPassword}}
+    </p>
 		<input type="submit"/>
 	</form>
 </template>
@@ -173,7 +173,7 @@ We can also pass a validation function and specify `validationMode: 'onSubmit'`
 
 ## Custom validation
 
-```vue
+```vue{20-22}
 <template>
   <form @submit.prevent="handleSubmit(successFn)">
     <input type="email" v-bind="register('email', {
@@ -224,7 +224,7 @@ Submission is really made easy, we can call the function the handler provides us
 
 If the submission fails it will call the error function we pass with the errors if available, if no error function is provided, then it will throw an error that you can catch from the upper context.
 
-```vue
+```vue{2,37-42}
 <template>
   <form @submit.prevent="handleSubmit(successFn, errorFn)">
     <input type="email" v-bind="register('email', {

src/logic/refFn.ts

@@ -25,16 +25,16 @@ export default (name: string, _refs: Refs, values: any) => (fieldRef: any) => {
             : fieldRef
     }
     if (isRadioInput(fieldRef)) {
-        if (isFirstRegister && fieldRef.checked) {
+        if (isFirstRegister && !!fieldRef.checked) {
             values[name] = fieldRef.value
             return
         }
         fieldRef.checked = (values[name] === fieldRef.value)
         return
     }
     if (isCheckboxInput(fieldRef)) {
-        if (isFirstRegister) {
-            values[name] = !!fieldRef.checked
+        if (isFirstRegister && !!fieldRef.checked) {
+            values[name] = true
             return
         }
         fieldRef.checked = !!values[name]

src/test/handler.test.ts

@@ -45,19 +45,10 @@ describe('Form handler testing', () => {
         expect(formState.errors).toStrictEqual({ field: { error: 'some error' } })
         expect(formState.isValid).toBeFalsy()
     })
-    it('Clearing one error of a control programmatically', async () => {
+    it('Clearing an error programmatically', async () => {
         const { formState, setError, clearError } = useFormHandler();
-        const errors = { error: 'some error', error2: 'some other error' }
-        setError('field', errors)
-        expect(formState.isValid).toBeFalsy()
-        clearError('field', 'error')
-        expect(formState.errors.field).toStrictEqual({ error2: 'some other error' })
-        expect(formState.isValid).toBeFalsy()
-    })
-    it('Clearing all errors of a control programmatically', async () => {
-        const { formState, setError, clearError } = useFormHandler();
-        const errors = { error: 'some error', error2: 'some other error' }
-        setError('field', errors)
+        const error = 'This field has an error'
+        setError('field', error)
         expect(formState.isValid).toBeFalsy()
         clearError('field')
         expect(formState.errors.field).toBeUndefined()

src/types/formHandler.ts

@@ -1,3 +1,4 @@
+import { ComputedRef, Ref } from "vue"
 import { RegisterOptions, Register } from "./register"
 
 export interface FormState {
@@ -51,13 +52,13 @@ export type ResetField = (name: string) => void
 export type ResetForm = () => void
 
 /** Function to set an error programmatically */
-export type SetError = (name: string, error: any, replace?: boolean) => void
+export type SetError = (name: string, error: any) => void
 
 /** Function to clear an error programmatically */
-export type ClearError = (name?: string, errors?: string | string[]) => void
+export type ClearError = (name?: string) => void
 
 /** Function to get the modified values of the form */
-export type ModifiedValues = () => Object
+export type ModifiedValues = () => Record<string, any>
 
 /** Expected function to be called after a form submitted successfully */
 export type HandleSubmitSuccessFn = (values: Object) => void
@@ -96,24 +97,32 @@ export interface InterceptorParams {
     /** Function to set an error on a field programmatically */
     setError: SetError
 
+    /** Function to set the value of a field programmatically */
+    setValue: SetValue
+
     /** Function to clear one or more errors on a desired field or the whole form*/
     clearError: ClearError
 
+    /** Function to clear a desired field*/
+    clearField: ClearField
+
     /** Function that returns the modified values of the form */
     modifiedValues: ModifiedValues
 }
 
-export type Interceptor = (_: InterceptorParams) => Promise<boolean>
+export type Interceptor = (_: InterceptorParams) => Promise<boolean> | boolean
+
+export type FormValidation = (values: Record<string, any>) => Promise<boolean> | boolean
 
 export interface FormHandlerParams {
     /** Values to initialize the form */
-    initialValues?: Record<string, any>
+    initialValues?: Record<string, any> | Ref<Record<string, any>> | ComputedRef<Record<string, any>>
 
     /** Field change interceptor */
     interceptor?: Interceptor
 
     /** Validation function to execute before submitting (when using this individual validations are invalidated) */
-    validate?: () => Promise<boolean> | boolean
+    validate?: FormValidation
 
     /** Validation behavior options */
     validationMode?: 'onChange' | 'onBlur' | 'onSubmit' | 'always'