Form.md

<Form />

import { Form as CForm } from 'vue-controlled-form-fields';

Form is a subscription-based state manager and provider which uses the Vue's power and Reactivity to provide the state and functionality to children or the component which the Form has been defined and used.

Form :props

Properties	Type	Default	Example
submit	Function or Promise	required	Link
Will return current values of the form in case of there wasn't any validation errors in form state. The touched `property` in all fields states will be set to true. If you return a `Promise` in submit function `submitting` property in form state will be set to true after resolving will be set to false.
subscription	{ [string]: boolean }	undefined	Link
The form will only re-render when these fields in state changes. Could be useful for performance. Also when you use form.subscribe() you can pass subscription items in second parameter. If you pass nothing then everything will be subscribed.
initialValues	Object	undefined	Link
Will initialize the form on created life cycle, if it's changes the form will re-initialized. the fields with property names will be registered before mounting the field components.
keepDirtyOnReinitialize	Boolean	false	Link
When you pass true, After re-initializing the form, The dirty `property` in all fields states won't change. will be same as it was before. But by default which is false, after re-initializing dirty properties will be set to false.
validate	Function	undefined	Link
You can validate your fields by passing pure functions and returning an object with the same name of your field.
validateOnBlur	Boolean	false	Link
Validation functions will be called after triggering @blur function. This could be effective when you have more than 1000 fields at the same page.
destroyOnUnregister	Boolean	false	Link
If you pass it true, When the field has been removed from DOM the state of field will be there.

Form @events

Events	Parameters	default	Example
@created	FormState including Form Object	undefined	Link
This event occurs before rendering the form in DOM. Could be useful when you need to use subscribe the form state or use form methods in the current component which the form has been defined.
@---formState properties	Value of the subscribed property in form state	undefined	Link
You can listen to changes of single property of form state. e.g. @values, @dirty, @submitting. Won't be triggered if you do not pass the property it as subscription items. If you pass nothing by default will be trigger.

Form {}State

Each Form and Field has a state which includes some properties which have special meaning and they happened in the special time.

Properties	Type	Example
dirty	Boolean	Link
Will be true if the form has any fields with dirty = true
valid	Boolean	Link
Will be true if all the fields hasn't any errors
invalid	Boolean	Link
Will be true if a field has error
visited	Boolean	Link
Will be true if the form has any fields with visited = true
modified	Boolean	Link
Will be true if the form has any fields with modified = true
pristine	Boolean	Link
Will be true if the form has any fields with pristine = true
touched	Boolean	Link
Will be true if the form has any fields with touched = true
active	Boolean	Link
Name of the field which user focused on it, will be disapear when blur() has been called
submitting	Boolean	Link
Will be true if submit method returns Promise
values	Object	Link
Current values of the form
errors	Object	Link
Current errors of the form
dirtyFields	Object	Link
List of dirty fields
modifiedFields	Object	Link
List of modified fields
visitedFields	Object	Link
List of visited fields
initialValues	Object or undefined	Link
InitialValues which passed to form as a prop or through the form.initialize() method
[form]()	Object	Link
Has several methods for manipulating the state and getting state or specific property and more.

We can access to form state in two ways:

1. slot-scope in template

<template>
  <c-form>
  	<div slot-scope="formState">
       <field name="username" component="input" type="text" />
       <button :disabled="formState.invalid || formState.pristine"></button>
     </div>
  </c-form>
</template>

2. Life cycle hooks@created and form.subscribe

<template>
  <c-form @change="onChangeFormState" @created="onFormCreated">
  	<field name="username" component="input" type="text" />
  </c-form>
</template>

<script>
export default {
  data() {
    return {
		form: null
    };
  },
  mounted() {
  	const unsubscribe = this.form.subscribe(state => {
    	console.log(state);
    });
  },
  methods: {
  	onFormCreated(form) {
    	this.form = form;
    },
    onChangeFormState({ values }) {
    	console.log(values);
    }
  }
};
</script>

Your listeners can be specific and listen only for one key and the changes of it, like @errors, @values. Actually your $listeners are listening to changes by form.subscribe(callback, { ...subscription }).

Form Methods()

Methods	Accepted Parameters	Example
handleSubmit	-	Link
Will trigger the submit method from props
initialize	Object or Function(currentValues => ({}))	Link
Will initialize the form, You can pass Object or Function. If you pass function then you can access to current values of form. And also take a look at keepDirtyOnReinitialize
reset	-	Link
Will reset the form state and fields states. Like they registered again.
change	(name: string, value: any)	Link
Will change the value of field directly. If you pass a name which is not registered before, Will register it. You should use object dot notation for nested properties.
focus	(name: string)	Link
Will change some properties in field state + form state, e.g touched, visited and more. Will be useful when you want to show validation errors. By calling this method the name which passed as first argument will set in to the active property in form state. You should use object dot notation for nested properties.
blur	(name: string)	Link
Will change some properties in field state + form state, e.g touched, visited and more. Will be useful when you want to show validation errors. By calling this method the name which passed as first argument will set in to the active property in form state. You should use object dot notation for nested properties.
subscribe	(Function(formState => {}), { [string]: boolean })	Link
Will subscribe the form state and will pass the form state as first argument. You can pass subscription to list only for specific changes based on items you passed in second argument. Will return a function for unsubscribing the state.
getFieldState	(name: string)	Link
Will return current field state.
getFormState	-	Link
Will return current form state.
getRegisteredFields	-	Link
Will return Array of strings which are name of fields which registered in form state.