⚡️ WIP: Api reference

Author: Daniel Requejo

docs/.vitepress/config.cts

@@ -20,36 +20,36 @@ export default defineConfig({
     },
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Get started', link: '/get-started' },
+      { text: 'Get started', link: '/get-started/introduction' },
     ],
     sidebar: [
       {
-        text: 'Documentation', items: [
-          { text: 'Get started', link: '/get-started' },
-          { text: 'Tutorial', link: '/tutorial' },
-          {
-            text: 'Guides', items: [
-              { text: 'Validation', link: '/guides/validation' },
-              { text: 'Typescript', link: '/guides/typescript' },
-              { text: 'Form submission', link: '/guides/form-submission' },
-              { text: 'Custom components', link: '/guides/custom-components' },
-              { text: 'Native support', link: '/guides/native-support' },
-            ]
-          },
-          {
-            text: 'Examples', items: [
-              { text: 'Basic', link: '/examples/basic' },
-              { text: 'Async validations', link: '/examples/async-validations' },
-              { text: 'Typescript', link: '/examples/typescript' },
-              { text: 'Interceptor', link: '/examples/interceptor' },
-              { text: 'Dependent fields', link: '/examples/dependent-fields' },
-              { text: 'More examples', link: '/examples/more-examples' }
-            ]
-          },
+        text: 'Get started', items: [
+          { text: 'Introduction', link: '/get-started/introduction' },
+          { text: 'Quick Start', link: '/get-started/quick-start' },
+        ]
+      },
+      {
+        text: 'Guides', collapsible: true, items: [
+          { text: 'Validation', link: '/guides/validation' },
+          { text: 'Typescript', link: '/guides/typescript' },
+          { text: 'Form submission', link: '/guides/form-submission' },
+          { text: 'Custom components', link: '/guides/custom-components' },
+          { text: 'Native support', link: '/guides/native-support' },
+        ]
+      },
+      {
+        text: 'Examples', collapsible: true, items: [
+          { text: 'Basic', link: '/examples/basic' },
+          { text: 'Async validations', link: '/examples/async-validations' },
+          { text: 'Typescript', link: '/examples/typescript' },
+          { text: 'Interceptor', link: '/examples/interceptor' },
+          { text: 'Dependent fields', link: '/examples/dependent-fields' },
+          { text: 'More examples', link: '/examples/more-examples' }
         ]
       },
       {
-        text: 'API Reference', items: [
+        text: 'API Reference', collapsible: true, items: [
           {
             text: 'useFormHandler', link: '/api/use-form-handler/',
             items: [

docs/api/form-handler.md

@@ -1,4 +1,4 @@
-# \<FormHandler/>: <font size="3">Component</font>
+# \<FormHandler/>
 
 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. 
 

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

@@ -1,4 +1,4 @@
-# clearError: <font size="3">ClearError</font>
+# clearError
 
 Clears all the errors from the form or the error from a field programmatically.
 
@@ -20,7 +20,7 @@ Coming soon...
     </form>
 </template>
 <script setup lang="ts" >
-import { useFormHandler, Interceptor } from '../src/index'
+import { useFormHandler, Interceptor } from 'vue-form-handler'
 
 const sleep = (milliseconds: number) => {
     return new Promise(resolve => setTimeout(resolve, milliseconds))
@@ -65,7 +65,7 @@ Notice how we use the combination of [setError](/api/use-form-handler/set-error)
     </form>
 </template>
 <script setup lang="ts" >
-import { useFormHandler } from '../src/index'
+import { useFormHandler } from 'vue-form-handler'
 import { watch } from 'vue'
 
 let hasErrorsAfterSubmit = false;

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

@@ -1,4 +1,4 @@
-# clearField: <font size="3">ClearField</font>
+# clearField
 
 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.
@@ -53,7 +53,7 @@ const { register } = useFormHandler({
     <button @click="clearField('clearableField')">X</button>
 </template>
 <script setup lang="ts" >
-import { useFormHandler } from '../src/index'
+import { useFormHandler } from 'vue-form-handler'
 
 const { register, clearField } = useFormHandler()
 </script>

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

@@ -1,4 +1,4 @@
-# formState: <font size="3">FormState</font>
+# formState
 
 Provides you with the reactive state of the form, including validation, dirty and touched state, for the whole form or individual fields.
 
@@ -35,13 +35,13 @@ Provides you with the reactive state of the form, including validation, dirty an
     </form>
 </template>
 <script setup lang="ts" >
-import { useFormHandler } from '../src/index'
+import { useFormHandler } from 'vue-form-handler'
 
 const { register, formState } = useFormHandler()
 </script>
 ```
 
-## Type Declaration
+## Type Declarations
 
 ```ts
 export interface FormState {

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

@@ -1,4 +1,4 @@
-# handleSubmit: <font size="3">HandleSubmit</font>
+# handleSubmit
 
 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.
 
@@ -24,7 +24,7 @@ Coming soon...
     </form>
 </template>
 <script setup lang="ts" >
-import { useFormHandler } from '../src/index'
+import { useFormHandler } from 'vue-form-handler'
 
 const { register, handleSubmit, formState } = useFormHandler()
 const successFn = (form: any) => {
@@ -58,7 +58,7 @@ const submitFn = () => {
     </form>
 </template>
 <script setup lang="ts" >
-import { useFormHandler } from '../src/index'
+import { useFormHandler } from 'vue-form-handler'
 
 const { register, handleSubmit } = useFormHandler()
 const successFn = (form: any) => {
@@ -72,7 +72,7 @@ const errorFn = (errors:any) => {
 </script>
 ```
 
-## Type Declaration
+## Type Declarations
 
 ```ts
 export type HandleSubmitSuccessFn = (values: Record<string, any>) => void

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

@@ -1,4 +1,4 @@
-# useFormHandler: <font size=3>FormHandler</font>
+# useFormHandler
 
 `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.
 
@@ -157,4 +157,48 @@ Using the `always` validationMode will have a more significant impact on perform
 - [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)
+- [values](/api/use-form-handler/values)
+
+## Type Declarations
+
+```ts
+
+export type Interceptor = (
+    _: InterceptorParams
+) => Promise<boolean> | boolean
+
+export type FormValidation = (
+    values: Record<string, any>
+) => Promise<boolean> | boolean
+
+export interface FormHandlerParams {
+    initialValues?: Record<string, any> 
+    | Ref<Record<string, any>> 
+    | ComputedRef<Record<string, any>>
+    interceptor?: Interceptor
+    validate?: FormValidation
+    validationMode?: 'onChange' 
+    | 'onBlur' 
+    | 'onSubmit' 
+    | 'always'
+}
+export interface FormHandlerReturn {
+    formState: FormState
+    values: Record<string, any>
+    clearError: ClearError
+    clearField: ClearField
+    handleSubmit: HandleSubmit
+    modifiedValues: ModifiedValues
+    register: Register
+    resetField: ResetField
+    resetForm: ResetForm
+    setError: SetError
+    setValue: SetValue
+    triggerValidation: TriggerValidation
+    unregister: (name: string) => void
+}
+
+export type FormHandler = (
+    _?: FormHandlerParams
+) => FormHandlerReturn
+```

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

@@ -1 +1,43 @@
-# modifiedValues
+# modifiedValues
+
+Returns the current modified fields of the form.
+
+## Demo
+
+Coming soon...
+
+## 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')">
+        <pre>
+            {{ modifiedValues() }} //should be initially
+        </pre>
+        <pre>
+            {{ values }} //should be filled with the initial values
+        </pre>
+    </form>
+</template>
+<script setup lang="ts" >
+import { useFormHandler } from 'vue-form-handler'
+
+const { register, values, modifiedValues } = useFormHandler({
+    initialValues: {
+        name: 'My name',
+        email: 'myemail@mail.com'
+    }
+})
+</script>
+```
+
+Let's say your form is initialized as above, because you're editing an existing item, and you just want to be aware of the data that changed to perform a `PATCH` operation, then `modifiedValues` is your best friend.
+
+## Type Declarations
+
+```ts
+export type ModifiedValues = () => Record<string, any>
+```

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

@@ -1,4 +1,4 @@
-# values:  <font size="3">Record<string, any></font>
+# values
 
 Provides you with the reactive state of the form, including validation, dirty and touched state, for the whole form or individual fields.
 
@@ -30,13 +30,13 @@ Provides you with the reactive state of the form, including validation, dirty an
     </section>
 </template>
 <script setup lang="ts" >
-import { useFormHandler } from '../src/index'
+import { useFormHandler } from 'vue-form-handler'
 
 const { register, values } = useFormHandler()
 </script>
 ```
 
-## Type Declaration
+## Type Declarations
 
 ```ts
 export type Values = Record<string, any>

docs/get-started.md renamed to docs/get-started/introduction.md

@@ -1,4 +1,4 @@
-# Get started
+# Introduction
 
 VueFormHandler is an abstract and flexible form handling solution. It allows you to easily handle forms in Vue, without forcing you to use specific components. You can use it on along with native HTML, custom components and material libraries (Quasar, Vuetify, Oruga...). It builds on top of Vue using typescript and provides a comfortable and efficient way to handle your forms.