Merge pull request #62 from dbssman/feature/55-add-composableutil-for-prop-binding-generation

🧱 Add build function and documentation

Author: dbssman

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/test/component.test.ts

@@ -2,14 +2,14 @@ import { FormHandler } from '../FormHandler'
 import { mount } from '@vue/test-utils'
 import { expect, it, describe } from 'vitest'
 
-describe('FormHandler component testing', () => {
-  it('Form handler gets mounted', () => {
+describe('FormHandler', () => {
+  it('should mount', () => {
     expect(FormHandler).toBeTruthy()
 
     const wrapper = mount(FormHandler)
     expect(wrapper.exists()).toBeTruthy()
   })
-  it('Form handler scoped slot provides values and form state', () => {
+  it('should provide values and formState', () => {
     expect(FormHandler).toBeTruthy()
 
     const wrapper = mount(FormHandler, {
@@ -23,7 +23,7 @@ describe('FormHandler component testing', () => {
     expect(wrapper.html()).toContain('values')
     expect(wrapper.html()).toContain('formState')
   })
-  it('Form handler is correctly initialized', () => {
+  it('should be properly initialized', () => {
     const initialValues = {
       field1: 'something',
       field2: 'some other thing',

src/test/handler.test.ts

@@ -1,26 +1,26 @@
 import { initialState, useFormHandler } from '../useFormHandler'
 import { expect, it, describe } from 'vitest'
 
-describe('Form handler testing', () => {
-  it('Initial form state and values', () => {
+describe('useFormHandler()', () => {
+  it('should have correct initial state and values', () => {
     const { values, formState } = useFormHandler()
     expect(values).toStrictEqual({})
     expect(formState).toStrictEqual({ ...initialState() })
   })
-  it('Initial values should be applied without', () => {
+  it('should apply initialValues when specified', () => {
     const initialValues = {
       field: 'test',
     }
     const { values } = useFormHandler({ initialValues })
     expect(values).toStrictEqual(initialValues)
   })
-  it('Setting a value programmatically', async () => {
+  it('should set a value programmatically', async () => {
     const { values, setValue, formState } = useFormHandler()
     await setValue('field', 'oneTwoThree')
     expect(values.field).toBe('oneTwoThree')
     expect(formState.isDirty).toBeTruthy()
   })
-  it('Clearing a field programmatically', async () => {
+  it('should clear a field', async () => {
     const { register, values, setValue, formState, clearField } =
       useFormHandler()
     register('field')
@@ -31,7 +31,7 @@ describe('Form handler testing', () => {
     expect(values.field).toBe(null)
     expect(formState.isDirty).toBeFalsy()
   })
-  it('Clearing an initialized field leaves it dirty', async () => {
+  it('should leave an initialized field dirty when clearing', async () => {
     const { register, values, formState, clearField } = useFormHandler({
       initialValues: { field: 'value' },
     })
@@ -42,13 +42,13 @@ describe('Form handler testing', () => {
     expect(values.field).toBe(null)
     expect(formState.isDirty).toBeTruthy()
   })
-  it('Setting an error programmatically', async () => {
+  it('should set an error programmatically', async () => {
     const { formState, setError } = useFormHandler()
     setError('field', 'some error')
     expect(formState.errors).toStrictEqual({ field: 'some error' })
     expect(formState.isValid).toBeFalsy()
   })
-  it('Clearing an error programmatically', async () => {
+  it('should clear an error programmatically', async () => {
     const { formState, setError, clearError } = useFormHandler()
     const error = 'This field has an error'
     setError('field', error)
@@ -57,7 +57,7 @@ describe('Form handler testing', () => {
     expect(formState.errors.field).toBeUndefined()
     expect(formState.isValid).toBeTruthy()
   })
-  it('Clearing all errors of the form programmatically', async () => {
+  it('should clear all form errors programmatically', async () => {
     const { formState, setError, clearError } = useFormHandler()
     const error = 'some error'
     setError('field1', error)
@@ -70,7 +70,7 @@ describe('Form handler testing', () => {
     expect(formState.errors.field2).toBeUndefined()
     expect(formState.isValid).toBeTruthy()
   })
-  it('Resetting a field it back to its initial values and state', async () => {
+  it('should correctly reset a field', async () => {
     const { values, formState, resetField, setValue } = useFormHandler({
       initialValues: { field: 'value' },
     })
@@ -83,7 +83,7 @@ describe('Form handler testing', () => {
     expect(values.field).toBe('value')
     expect(formState.isDirty).toBeFalsy()
   })
-  it('Expecting modifiedValues to work', async () => {
+  it('should return correct modifiedValues', async () => {
     const { modifiedValues, setValue } = useFormHandler({
       initialValues: {
         field: 'something',
@@ -92,4 +92,21 @@ describe('Form handler testing', () => {
     await setValue('field2', 'another thing')
     expect(modifiedValues()).toStrictEqual({ field2: 'another thing' })
   })
+  it('should register field properly via build', () => {
+    const { build, values } = useFormHandler()
+    const form = build({
+      field: {},
+    })
+
+    expect(form.value.field.name).toBe('field')
+    expect(form.value.field.error).toBeUndefined()
+    expect(form.value.field.onBlur).toBeDefined()
+    expect(form.value.field.isDirty).toBeUndefined()
+    expect(form.value.field.isTouched).toBeUndefined()
+    expect(form.value.field.onClear).toBeDefined()
+    expect(form.value.field.onChange).toBeDefined()
+    expect(form.value.field.modelValue).toBe(null)
+    expect(form.value.field['onUpdate:modelValue']).toBeDefined()
+    expect(values.field).toBe(null)
+  })
 })

src/test/register.test.ts

@@ -1,8 +1,8 @@
 import { describe, it, expect } from 'vitest'
 import { useFormHandler } from '../useFormHandler'
 
-describe('Register function testing', () => {
-  it('Registering a field', () => {
+describe('register()', () => {
+  it('should register a field', () => {
     const { values, register } = useFormHandler()
     const field = register('field')
     expect(field.name).toBe('field')
@@ -16,31 +16,37 @@ describe('Register function testing', () => {
     expect(field['onUpdate:modelValue']).toBeDefined()
     expect(values.field).toBe(null)
   })
-  it('Specified native field should have native handlers', () => {
+  it('should apply native handlers by default', () => {
+    const { register } = useFormHandler()
+    const field = register('field')
+    expect(field.ref).toBeDefined()
+    expect(field.onChange).toBeDefined()
+  })
+  it('should apply native handlers when native is specified', () => {
     const { register } = useFormHandler()
     const field = register('field', { native: true })
     expect(field.ref).toBeDefined()
     expect(field.onChange).toBeDefined()
   })
-  it("Specified custom field shouldn't have native handlers", () => {
+  it('should not apply native handlers when native is set false', () => {
     const { register } = useFormHandler()
     const field = register('field', { native: false })
     expect(field.onChange).toBeUndefined()
     expect(field.modelValue).toBeDefined()
     expect(field['onUpdate:modelValue']).toBeDefined()
   })
-  it('Input registered with details receives dirty and touched states', () => {
+  it('should apply dirty and touched states when withDetails is specified', () => {
     const { register } = useFormHandler()
     const field = register('field', { withDetails: true })
     expect(field.isDirty).toBeDefined()
     expect(field.isTouched).toBeDefined()
   })
-  it('Registering a field with default value', () => {
+  it('should apply default value', () => {
     const { values, register } = useFormHandler()
     register('field', { defaultValue: 'something' })
     expect(values.field).toBe('something')
   })
-  it('Registered validations work on update via handler', async () => {
+  it('should trigger validation via handler', async () => {
     const { values, register, formState } = useFormHandler()
     const field = register('field', {
       validate: {
@@ -53,7 +59,7 @@ describe('Register function testing', () => {
       expect(formState.isValid).toBeFalsy()
     }
   })
-  it('Registered validations work on update via setter', async () => {
+  it('should trigger validation via setter', async () => {
     const { values, register, formState, setValue, triggerValidation } =
       useFormHandler()
     register('field', {

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,