docs: update form validation docs

inkline · Oct 25, 2023 · 8556fcd · 8556fcd · vercel · Oct 25, 2023
1 parent 50dd607
commit 8556fcd
Show file tree

Hide file tree

Showing 5 changed files with 115 additions and 110 deletions.
diff --git a/components/app/sidebar/Navigation.vue b/components/app/sidebar/Navigation.vue
@@ -3,7 +3,7 @@ import { computed, defineComponent, inject, PropType } from 'vue';
 import { useI18n } from 'vue-i18n';
 import { useRoute } from 'vue-router';
 import { CollapsibleNavigationPage, NavigationPage } from '~/types';
-import { NavbarKey } from '@inkline/inkline/components/INavbar/mixin';
+import { NavbarKey } from '@inkline/inkline/constants';
 
 export default defineComponent({
     props: {

diff --git a/content/docs/forms/validation/index.md b/content/docs/forms/validation/index.md
@@ -9,14 +9,15 @@ description: Inkline provides you with powerful form validation utilities.
 The built-in Form Validation package allows you to define a form validation schema which you will bind to your form components. 
 
 Using this declarative approach has several advantages and allows for easy and intuitive form validation:
-- centralized form validation schema
+- maintainable form validation schema
 - programmatically customizable and extendable
 - schema nesting and nested form validation
 - built-in validation status propagation
+- easy serialization
 - clean template markup
 
 ### Basic Example
-Let's create a basic login form that has a `username` and a `password` field. Validation for this kind of form is usually a headache, but Inkline makes it simple for you. Basic validation for these fields usually includes:
+Let's create a basic signup form that has a `username` and a `password` field. Validation for this kind of form is usually a headache, but Inkline makes it simple for you. Basic validation for these fields usually includes:
 - The username is required
 - The password is required
 - The password is at least 8 characters long
@@ -25,53 +26,35 @@ Let's create a basic login form that has a `username` and a `password` field. Va
 - The password contains at least one numeric character 
 - The password contains at least one symbol
 
-#### 1. Defining the form schema
-First, we'll create our schema with two fields: `username` and `password`. The form validation schema prototype is available for both the Options API and the new Composition API. Choose the one that you prefer.
-
-##### a. Composition API 
-
-The form schema prototype is created using the `useForm` utility inside components and will be used as the foundation for form validation schemas.
-
-~~~js
-import { defineComponent } from 'vue';
-import { useForm } from '@inkline/inkline';
+The form validation schema prototype is available for both the Options API and the Composition API. Choose the one that you prefer.
 
-export default defineComponent({
-    setup() {
-        const schema = {
-            username: {},
-            password: {},
-        };
-        const form = useForm(schema);
+#### 1. Defining the form schema
+First, we'll create our schema with two fields: `username` and `password`. 
 
-        return {
-            form
-        };   
-    }       
-});   
-~~~
+The form schema prototype is created using the `useForm` utility inside components and will be used as the foundation for form validation schemas. The composable is type safe and requires a generic base type that determines the shape of your form. 
 
-##### b. Options API
-The form schema prototype will created using `this.$inkline.form` inside components and will be used as the foundation for form validation schemas.
+There are three values being returned by the `useForm` composable:
+- `schema` - the resolved schema with all validation fields
+- `form` - the serialized form values, computed based on the schema
+- `validate` - a function to validate the schema on demand
 
-~~~js
-export default {
-    data() {
-        const schema = {
-            username: {},
-            password: {},
-        };
+~~~html
+<script lang="ts" setup>
+import { useForm } from '@inkline/inkline';
 
-        return {
-            form: this.$inkline.form(schema)
-        };   
-    }       
-}       
+const { schema } = useForm<{
+    username: string;
+    password: string;
+}>({
+    username: {},
+    password: {},
+});
+</script>
 ~~~
 
-#### 2. Connecting the schema to the form components
+#### 2. Connecting the form schema to the form components
 
-Next, the created `form` object needs to be bound to the form input components inside your template as follows:
+Next, the created `schema` object needs to be bound to the form input components inside your template as follows:
  - The form component handles field value changes using the `v-model` directive
  - Each field name inside the defined schema connects to an input using the `name` property in your template
 
@@ -82,65 +65,60 @@ Next, the created `form` object needs to be bound to the form input components i
 <!-- Autodocs{src="@inkline/inkline/stories/forms/validation/basic-binding.raw.vue" lang="vue"} -->
 ::
 
-For the example above, `this.form.username` and `this.form.password` would be objects containing the field value, errors and validation statuses.
+For the example above, `schema.value.username` and `schema.value.password` would be objects containing the field value, errors and validation statuses.
 
-#### 3. Adding the field validators
+#### 3. Adding the form validators
 
 Next, let's add the previously mentioned validators to the created form schema:
 
-~~~js
-import { defineComponent } from 'vue';
+~~~html
+<script lang="ts" setup>
 import { useForm } from '@inkline/inkline';
 
-export default defineComponent({
-    setup() {
-        const schema = {
-            username: {
-                validators: [
-                    { 
-                        name: 'required' 
-                    }
-                ]
+const { schema } = useForm<{
+    username: string;
+    password: string;
+}>({
+    username: {
+        validators: [
+            {
+                name: 'required'
+            }
+        ]
+    },
+    password: {
+        validators: [
+            {
+                name: 'required'
+            },
+            {
+                name: 'minLength',
+                value: 8
+            },
+            {
+                name: 'custom', // lowercase
+                message: 'Please enter at least one lowercase character.',
+                validator: (v) => /[a-z]/.test(v)
+            },
+            {
+                name: 'custom', // uppercase
+                message: 'Please enter at least one uppercase character.',
+                validator: (v) => /[A-Z]/.test(v)
             },
-            password: {
-                validators: [
-                    { 
-                        name: 'required' 
-                    },
-                    { 
-                        name: 'minLength', 
-                        value: 8 
-                    },
-                    {
-                        name: 'custom', // lowercase
-                        message: 'Please enter at least one lowercase character.',
-                        validator: (v) => /[a-z]/.test(v)
-                    },
-                    {
-                        name: 'custom', // uppercase
-                        message: 'Please enter at least one uppercase character.',
-                        validator: (v) => /[A-Z]/.test(v)
-                    },
-                    {
-                        name: 'custom', // numeric
-                        message: 'Please enter at least one numeric character.',
-                        validator: (v) => /[0-9]/.test(v)
-                    },
-                    {
-                        name: 'custom', // symbol
-                        message: 'Please enter at least one symbol.',
-                        validator: (v) => /[^a-zA-Z0-9]/.test(v)
-                    }
-                ]
+            {
+                name: 'custom', // numeric
+                message: 'Please enter at least one numeric character.',
+                validator: (v) => /[0-9]/.test(v)
+            },
+            {
+                name: 'custom', // symbol
+                message: 'Please enter at least one symbol.',
+                validator: (v) => /[^a-zA-Z0-9]/.test(v)
             }
-        };
-        const form = useForm(schema);
-
-        return {
-            form
-        };   
-    }       
-});    
+        ]
+    }
+});
+</script>
 ~~~
 
 ::ContentTabs
@@ -150,18 +128,35 @@ export default defineComponent({
 <!-- Autodocs{src="@inkline/inkline/stories/forms/validation/basic-validators.raw.vue" lang="vue"} -->
 ::
 
-You can also register custom validators for your form schema.
+You can also register custom validators for your form schema. [Read more](/docs/forms/validation/validators) about validators.
 
-### Validation Statuses
-Did you see how simple that was? Makes writing form validation a breeze. Behind the scenes, the validation utility will validate values using the set of rules you define, handle the displaying of error messages and provide you with useful `valid`, `invalid`, `touched`, `untouched`, `dirty` and `pristine` statuses. 
+#### 4. Enjoy!
 
-These fields will be set to `true` when:
+Did you see how simple that was? Inkline makes even the most advanced form validation a breeze. 
 
-- `valid` - the input value is correct
-- `invalid` - the input value is not correct
-- `touched` - the input has been touched and blurred
-- `untouched` - the input has not been touched
-- `dirty` - the input value has been changed
-- `pristine` - the input value has not been changed
+Behind the scenes, the validation utility will validate values using the set of rules you define, handle the displaying of error messages, automatically serialize the schema, and provide you with useful `valid`, `invalid`, `touched`, `untouched`, `dirty` and `pristine` statuses.
 
-To learn more about defining a form schema, head to the next page.
+### Using Options API (Deprecated)
+Although the Options API is deprecated, you can still use it to define your form schema.
+
+The form schema prototype will created using `this.$inkline.form` inside components and will be used as the foundation for creating form validation schemas.
+
+~~~js
+<script lang="ts">
+import { defineComponent } from 'vue';
+
+export default defineComponent({
+    data() {
+        return {
+            schema: this.$inkline.form<{
+                username: string;
+                password: string;
+            }>({
+                username: {},
+                password: {},
+            })
+        };   
+    }       
+});  
+</script>
+~~~
diff --git a/content/docs/forms/validation/schema.md b/content/docs/forms/validation/schema.md
@@ -7,11 +7,21 @@ description:  The validation schema defines the form input fields, groups and ho
 ## The validation schema defines the form input fields, groups and how they work together.
 
 From the [Overview](/docs/forms/validation) page we've learned:
-- The schema object provides form validation status fields such as `valid`, `invalid`, `touched`, `untouched`, `dirty`, `pristine` and `errors`
+- The schema object provides form validation state fields such as `valid`, `invalid`, `touched`, `untouched`, `dirty`, `pristine` and `errors`
 - The form component handles field value changes using the `v-model` directive
 - Each field name inside the defined schema connects to an input using the `name` property in your template
 - Using the `validators` field, you can specify an array of validators to be used on the field input
 
+### Form Validation State
+All form schema parts (root, groups, and fields) contain a very useful validation state, computed automatically. These following schema fields will be set to `true` when:
+
+- `valid` - the input value is correct
+- `invalid` - the input value is not correct
+- `touched` - the input has been touched and blurred
+- `untouched` - the input has not been touched
+- `dirty` - the input value has been changed
+- `pristine` - the input value has not been changed
+
 ### Default Field Value
 Providing a default value for a validation schema field can be done using the `value` field:
 

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -19,7 +19,7 @@
         "@docsearch/css": "3.5.1",
         "@docsearch/js": "3.5.1",
         "@grozav/utils": "1.3.2",
-        "@inkline/inkline": "4.3.3",
+        "@inkline/inkline": "^4.4.1",
         "copy-to-clipboard": "3.3.3",
         "date-fns": "2.30.0",
         "posthog-js": "1.75.3",