Form state, values and submit

Author: Daniel Requejo

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

@@ -1 +1,55 @@
-# formState
+# formState: <font size="3">FormState</font>
+
+Provides you with the reactive state of the form, including validation, dirty and touched state, for the whole form or individual fields.
+
+## Return
+
+| attribute | type   | description                                |
+|-----------|--------|--------------------------------------------|
+| dirty     | Record<string, boolean> | Object containing all the inputs that have been modified |
+| errors    | Record<string, string>  | Object containing all the current field errors of the form |
+| touched   | Record<string, boolean> | Object containing all the inputs the users has interacted with |
+| isDirty   | boolean | True if there is any modified field on the form |
+| isTouched | boolean | True if there has been any interaction with a form field |
+| isValid   | boolean | True if there are no form errors |
+
+## Rules
+
+`formState` is read-only, so no assignments are expected. It is entirely reactive, so you can react on changes of the whole element and/or it's main attributes.
+
+## Usage
+
+```vue
+<template>
+    <form>
+        <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'
+
+const { register, formState } = useFormHandler()
+</script>
+```
+
+## Type Declaration
+
+```ts
+export interface FormState {
+    isDirty: boolean
+    isTouched: boolean
+    isValid: boolean
+    dirty: Record<string, boolean>
+    touched: Record<string, boolean>
+    errors: Record<string, string>
+}
+```

docs/api/use-form-handler/handle-submit.md

@@ -1 +1,85 @@
-# handleSubmit
+# handleSubmit: <font size="3">HandleSubmit</font>
+
+Submits the form on demand, causing it's validation depending on the mode/validation function, and calls the success/error fn consequently based on the outcome.
+
+## Demo
+
+Coming soon...
+
+## Usage
+
+### Submit a form and catch if errors/issues on submitting
+
+```vue
+<template>
+    <form @submit.prevent="submitFn">
+        <input type="text" v-bind="register('name', {
+            required: true
+        })" />
+        <input type="text" v-bind="register('email', {
+            required: true
+        })" />
+        <input type="text" v-bind="register('summary')">
+        <button type="submit">Submit</button>
+    </form>
+</template>
+<script setup lang="ts" >
+import { useFormHandler } from '../src/index'
+
+const { register, handleSubmit, formState } = useFormHandler()
+const successFn = (form: any) => {
+    //do anything with form
+    console.log(form)
+}
+const submitFn = () => {
+    try {
+        handleSubmit(successFn)
+    } catch {
+        //do anything with errors
+        console.log(formState.errors)
+    }
+}
+</script>
+```
+
+### Submit a form and pass error function
+
+```vue
+<template>
+    <form @submit.prevent="handleSubmit(successFn,errorFn)">
+        <input type="text" v-bind="register('name', {
+            required: true
+        })" />
+        <input type="text" v-bind="register('email', {
+            required: true
+        })" />
+        <input type="text" v-bind="register('summary')">
+        <button type="submit">Submit</button>
+    </form>
+</template>
+<script setup lang="ts" >
+import { useFormHandler } from '../src/index'
+
+const { register, handleSubmit } = useFormHandler()
+const successFn = (form: any) => {
+    //do anything with form
+    console.log(form)
+}
+const errorFn = (errors:any) => {
+    //do anything with errors
+    console.log(errors)
+}
+</script>
+```
+
+## Type Declaration
+
+```ts
+export type HandleSubmitSuccessFn = (values: Record<string, any>) => void
+export type HandleSubmitErrorFn = (errors: Record<string, string>) => void
+
+export type HandleSubmit = (
+    successFn: HandleSubmitSuccessFn, 
+    errorFn?: HandleSubmitErrorFn
+) => void
+```

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

@@ -1 +1,43 @@
-# values
+# values:  <font size="3">Record<string, any></font>
+
+Provides you with the reactive state of the form, including validation, dirty and touched state, for the whole form or individual fields.
+
+## Return
+
+| attribute | type   | description                                |
+|-----------|--------|--------------------------------------------|
+| &lt;fieldName&gt; | any    | Current value of the specified field |
+## Rules
+
+`values` is read-only, so no assignments are expected. It is entirely reactive, so you can react on changes of the whole element and/or it's main attributes.
+
+## Usage
+
+```vue
+<template>
+    <form>
+        <input type="text" v-bind="register('name')" />
+        <input type="text" v-bind="register('email')" />
+        <input type="text" v-bind="register('summary')">
+    </form>
+    <section>
+        <h2>Preview:</h2>
+        <div>
+            <h3>Name: {{values.name}}</h3>
+            <h4>Email: {{values.email}}</h4>
+            <p>Summary: {{values.summary}}</p>
+        </div>
+    </section>
+</template>
+<script setup lang="ts" >
+import { useFormHandler } from '../src/index'
+
+const { register, values } = useFormHandler()
+</script>
+```
+
+## Type Declaration
+
+```ts
+export type Values = Record<string, any>
+```

src/types/formHandler.ts

@@ -61,10 +61,10 @@ export type ClearError = (name?: string) => void
 export type ModifiedValues = () => Record<string, any>
 
 /** Expected function to be called after a form submitted successfully */
-export type HandleSubmitSuccessFn = (values: Object) => void
+export type HandleSubmitSuccessFn = (values: Record<string, any>) => void
 
 /** Optional function to be called after a form failed to submit */
-export type HandleSubmitErrorFn = (errors: Object) => void
+export type HandleSubmitErrorFn = (errors: Record<string, string>) => void
 
 /** Checks for the validity of the form before submitting */
 export type IsValidForm = () => Promise<boolean>