docs: added validator docs

packages/docs/core-concepts/asyncValidatorExample.ts

@@ -0,0 +1,13 @@
+import { defineValidator, useField, useForm } from '@vuetils/form';
+
+const syncValidator = defineValidator('sync', (value) => true);
+const asyncValidator = defineValidator('async', async (value) => true);
+
+const form = useForm({
+	field: ['', [syncValidator], [asyncValidator]],
+});
+
+const field = useField('', {
+	validators: [syncValidator],
+	asyncValidators: [asyncValidator],
+});

packages/docs/core-concepts/defineValidatorExample.ts

@@ -0,0 +1,6 @@
+import { defineValidator } from '@vuetils/form';
+
+const validator = defineValidator('my-validator', (value) => {
+	// do some validating
+	return typeof value === 'string' && value.length > 0;
+});

packages/docs/core-concepts/defineValidatorWithArgsExample.ts

@@ -0,0 +1,6 @@
+import { defineValidatorWithArgs } from '@vuetils/form';
+
+const validator = defineValidatorWithArgs('my-validator', (value, shouldBe: string) => {
+	// do some validating
+	return typeof value === shouldBe;
+});

packages/docs/core-concepts/plugins.md

@@ -45,9 +45,9 @@ const form = useForm({
 form.addPlugin(localStoragePlugin('some-key'));
 ```
 
-## First Party Plugins
+## Built-in Plugins
 
-`@vuetils/form` comes with a few first party plugins that can be used out of the box.
+`@vuetils/form` comes with a set of built-in plugins that can be used out of the box.
 
 ### Storage Plugin
 

packages/docs/core-concepts/validators.md

@@ -1,11 +1,57 @@
+---
+outline: deep
+---
+
 # Validators
 
-## Native validators
+Validators are simple functions that take in the current field's value as first parameter and return a `boolean` indicating if the field is valid or not.
+
+## Built-in validators
+
+`@vuetils/form` comes with a set of built-in validators that can be used out of the box but it is also easy to [write your own](#write-your-own-validator).
+
+- `startsWith` - value is a string and starts with the given string
+- `regex` - value matches a regex
+- `email` - value is an email
+- `emoji` - value is an emoji
+
+These validators can be added to any `form` or `field` like so:
+
+```ts
+import { email, emoji, regex, startsWith, useForm, useField } from '@vuetils/form';
+
+const form = useForm({
+	field: ['', [email, emoji, regex(/regexIHardlyKnowHer/), startsWith('zwallo')]],
+});
+
+const field = useField('field', {
+	validators: [email, emoji, regex(/regexIHardlyKnowHer/), startsWith('zwallo')],
+});
+```
 
-When applicable `@vuetils/form` will use [native web valdiators](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#using_built-in_form_validation) like `required` or `minLength`. Try submitting the form in an invalid state and depending on your platform and browser a native validation warnign will appear.
+### HTML validation attributes
 
-## Additional validators
+HTML comes with a set of [validation attributes](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#using_built-in_form_validation) that let you validate your forms without JavaScript. Usually it is recommended to use these attrbutes even if you are validation you form with JavaScript. `@vuetils/form` has built-in equivalents for the following native validation attributes:
+
+- `required` - form field needs to be filled out
+- `minlength` and `maxlength` - min and max length of a string form field
+- `min` and `max` - min and max value of a numeric form field
+<!-- - `pattern` -->
+
+When used in combination with [`UField`](./components#ufield) or [`UForm`](./components#uform) these attributes will automatically be added to your input elements so you can have the best of both worlds.
 
 ## Async validators
 
+Async validators are like normal validators but their validation function returns a `Promise<boolean>` instead of a `boolean` . See how you can add both a sync and an async validator to a `field` or `form` in the example below.
+
+<<< ./asyncValidatorExample.ts
+
 ## Write your own validator
+
+`@vuetils/form` comes with the helper function `defineValidator` that makes it easy to write your own validator. The first argument is the name of your validator and the second argument is the validation function. The validation function takes in the current field's value as first parameter and returns a `boolean` indicating if the field is valid or not. The validation function is executed on every value change of a field.
+
+<<< ./defineValidatorExample.ts
+
+If your validator needs some extra arguments you can use `defineValidatorWithArgs` instead. The only difference to `defineValidator` is that the validation function will receive your custom arguments as the 2. parameter. When adding a type to the arguments, like `shouldBe: string` in the example below, your validator wil be type safe.
+
+<<< ./defineValidatorWithArgsExample.ts