🧱 Add build function and documentation

Author: Daniel Requejo

docs/.vitepress/config.cts

@@ -92,6 +92,7 @@ export default defineConfig({
                 link: '/api/use-form-handler/modified-values',
               },
               { text: 'register', link: '/api/use-form-handler/register' },
+              { text: 'build', link: '/api/use-form-handler/build' },
               { text: 'resetField', link: '/api/use-form-handler/reset-field' },
               { text: 'resetForm', link: '/api/use-form-handler/reset-form' },
               { text: 'setError', link: '/api/use-form-handler/set-error' },

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

@@ -0,0 +1,76 @@
+# build
+
+Builds a form based on the configuration passed, to leave a cleaner template and provide better readability over the whole form setup.
+
+## Demo
+
+Coming soon...
+
+## Usage
+
+### Build complex form fields and improve readability
+
+```vue
+<template>
+  <form @submit.prevent="() => handleSubmit(successFn, errorFn)">
+    <input type="text" v-bind="form.name" />
+    <input type="text" v-bind="form.email" />
+    <input type="text" v-bind="form.password" />
+    <input type="text" v-bind="form.passwordConfirmation" />
+    <button type="submit">Submit</button>
+  </form>
+</template>
+<script setup lang="ts">
+import { useFormHandler } from 'vue-form-handler'
+
+const successFn = (result: Record<string, any>) => { console.log(result) }
+const errorFn = (result: Record<string, string | undefined>) => { console.warn(result) }
+const { build, handleSubmit, values, formState } = useFormHandler()
+
+const form = build({
+  name: {
+    required: true,
+    pattern: {
+      value: /^[a-zA-Z]+$/,
+      message: 'Only letters are allowed'
+    }
+  },
+  email: {
+    required: true,
+    pattern: {
+      value: /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}$/,
+      message: 'Please enter a valid email'
+    }
+  },
+  password: {
+    required: true,
+    pattern: {
+      value: /^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[a-zA-Z]).{8,}$/,
+      message: 'Password must contain at least 8 characters, one uppercase, one lowercase and one number'
+    }
+  },
+  passwordConfirmation: {
+    required: true,
+    pattern: {
+      value: /^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[a-zA-Z]).{8,}$/,
+      message: 'Password must contain at least 8 characters, one uppercase, one lowercase and one number'
+    },
+    validate: {
+      match: (value: string) => value === values.password || 'Passwords do not match'
+    }
+  }
+})
+</script>
+```
+
+Notice how the template looks much cleaner with this approach, and this helps us to achieve better readability and is less confusing since we bind directly pieces of a form to each component/field on the template.
+
+## Type Declarations
+
+```ts
+export interface Build<T = Record<string, RegisterOptions>> {
+  (configuration: T | Ref<T> | ComputedRef<T>): ComputedRef<
+    Record<keyof T, RegisterReturn>
+  >
+}
+```

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

@@ -153,6 +153,7 @@ Using the `always` validationMode will have a more significant impact on perform
 - [handleSubmit](/api/use-form-handler/handle-submit)
 - [modifiedValues](/api/use-form-handler/modified-values)
 - [register](/api/use-form-handler/register)
+- [build](/api/use-form-handler/build)
 - [resetField](/api/use-form-handler/reset-field)
 - [resetForm](/api/use-form-handler/reset-form)
 - [setError](/api/use-form-handler/set-error)
@@ -187,6 +188,7 @@ export interface FormHandlerReturn {
   handleSubmit: HandleSubmit
   modifiedValues: ModifiedValues
   register: Register
+  register: Build
   resetField: ResetField
   resetForm: ResetForm
   setError: SetError

src/types/formHandler.ts

@@ -1,5 +1,5 @@
 import { ComputedRef, Ref } from 'vue'
-import { RegisterOptions, Register } from './register'
+import { RegisterOptions, Register, RegisterReturn } from './register'
 
 export interface FormState {
   /** Boolean holding the dirty state of the form */
@@ -77,6 +77,12 @@ export type HandleSubmit = (
   errorFn?: HandleSubmitErrorFn
 ) => void
 
+export interface Build<T = Record<string, RegisterOptions>> {
+  (configuration: T | Ref<T> | ComputedRef<T>): ComputedRef<
+    Record<keyof T, RegisterReturn>
+  >
+}
+
 export interface InterceptorParams {
   /** Name of the field that is currently about to be set*/
   name: string
@@ -159,6 +165,9 @@ export interface FormHandlerReturn {
   /** Method to register a field and make it interact with the current form */
   register: Register
 
+  /** Method to build a form configuration */
+  build: Build
+
   /** Function to reset a field */
   resetField: ResetField
 

src/useFormHandler.ts

@@ -1,3 +1,4 @@
+import { Build } from './types/formHandler'
 import { NativeValidations } from './types/validations'
 import { DEFAULT_FIELD_VALUE } from './constants'
 import {
@@ -23,8 +24,10 @@ import {
   ValidationsConfiguration,
   Unregister,
   FieldReference,
+  RegisterOptions,
+  RegisterReturn,
 } from './types'
-import { reactive, readonly, unref, watch } from '@vue/runtime-core'
+import { computed, reactive, readonly, unref, watch } from '@vue/runtime-core'
 import { isEqual } from 'lodash-es'
 import {
   getNativeFieldValue,
@@ -59,7 +62,7 @@ export const useFormHandler: UseFormHandler = ({
   const _getDefault = (name: string): any =>
     _refs[name]?._defaultValue ?? getDefaultFieldValue(_refs[name]?.ref)
   const _getInitial = (name: string): any =>
-    unref(initialValues)?.[name] ?? _getDefault(name)
+    (unref(initialValues) as Record<string, any>)?.[name] ?? _getDefault(name)
   const _initControl: InitControl = (name, options) => {
     const needsReset = options.disabled && _refs[name] && !_refs[name]._disabled
     _refs[name] = {
@@ -76,7 +79,11 @@ export const useFormHandler: UseFormHandler = ({
       unregister(name)
       return
     }
-    if (initialValues[name] === undefined && values[name] === undefined) {
+    if (
+      (!initialValues ||
+        (unref(initialValues) as Record<string, any>)?.[name] === undefined) &&
+      values[name] === undefined
+    ) {
       values[name] = _getDefault(name)
     }
   }
@@ -289,6 +296,16 @@ export const useFormHandler: UseFormHandler = ({
     }
   }
 
+  const build: Build = (configuration) => {
+    const staticConfig = unref(configuration) as Record<string, RegisterOptions>
+    return computed(() =>
+      Object.keys(staticConfig).reduce((acc, key) => {
+        acc[key] = register(key, staticConfig[key])
+        return acc
+      }, {} as Record<string, RegisterReturn>)
+    )
+  }
+
   const isValidForm: IsValidForm = async () => {
     if (validate) {
       return await validate(values)
@@ -322,6 +339,7 @@ export const useFormHandler: UseFormHandler = ({
     handleSubmit,
     modifiedValues,
     register,
+    build,
     resetField,
     resetForm,
     setError,