vue-form-container

A Provider Component that encapsulate your forms and handle their states and validations. Under the hood it uses valite, a light and concise validator engine that works on asynchrony. The idea of having a component handling the states and validations of the forms I took from formik and vue-final-form.

Installation

This library is published in the NPM registry and can be installed using any compatible package manager.

npm install --save vue-form-container

# Use the command below if you're using Yarn.
yarn add vue-form-container

Getting Started

Wrap your form, or wrapper element, with the FormContainer component passing the initial state of the fields and a scheme with the validations. Use slot-scope to receive the FormContainer scope with fields, errors, and so on.

<template>
  <form-container :initial="{ name: '' }" :schema="{
    name: [
      (name) => name.length > 0 || 'Name is required.'
    ]
  }">
    <div slot-scope="{ fields, errors }">
      <label>Name</label>
      <input v-model="fields.name" type="text" />
      <span>{{ errors.name }}</span>
    </div>

FormContainer is a renderless component, so it can receive just a single element as slot.

You can change the form field states and perform their validations using update functions or by changing the state of the fields object, which is a Proxy.

Due to platform limitations, fields (properties) need to be defined in schema or initial. If you don't want to initialize the value of a field, use undefined for it in initial or an empty list of validations in schema.

It is extremely important that the field exists on at least one of the objects.
<template>
  <form-container :initial="{ empty: undefined }">
  
  <form-container :schema="{ empty: [] }">

To use the FormContainer validations, fields and errors outside the template you should use a ref as in the example:

<template>
  <form-container ref="form" ... >
    <form ... @submit.prevent="onSubmit()">
      ...
      <button type="submit">Sign In</button>
    </form>
  </form-container>
</template>

<script>
  export default {
    methods: {
      async onSubmit () {
        // A FormContainer instance to handle fields, validate methods and other stuff.
        const form = this.$refs.form;

        await form.validateForm();
        if (!form.isValid)
          return;

        console.log('fields', form.fields);
      }
    }
  };
</script>

API

`FormContainer` props

Name	Type	Description
schema	`ValidatorSchema`	Schema of validators for form fields.
initial	`Object`	Initial state of form fields.

About ValidatorSchema type

ValidatorSchema is an object whose key is the name of the field and the value is a collection of validations. Validations are just functions that receive the value of the field and return true if it is valid and a string with the error message if it is invalid, these functions can also be asynchronous by returning a Promise that returns the same values (true or string with the error message).
type Validator = (value: any) => true | string | Promise<true | string>;

type ValidatorSchema = { [field: string]: Validator[]; };

...

const schema: ValidatorSchema = {
  name: [
    (name) => !!name.trim() || 'Name is required.',

    async (name) => {
      const isRepeated = await services.isRepeatedName(name);
      return !isRepeated || 'Name is repeated.';
    }
  ]
};

`FormContainer` properties and methods (also received by slot-scope)

Name	Type	Description
isValid	`boolean`	Indicates if form fields are valid.
isLoading	`boolean`	Indicates if there's a validation running.
errors	`MessageSchema`	Error scheme of form fields.
fields	`Proxy<{ [field: string]: any }>`	Proxy with form fields. It uses getters to get the state of the field and setters to update it.
update	`(field: string, value: any) => void`	Updates the state of the `field` using the `value`.
validateField	`(field: string) => Promise<void>`	Executes the schema validations for the `field` field.
validateForm	`() => Promise<void>`	Executes the validations on all fields specified in the schema.

About MessageSchema type

MessageSchema is a reflection of the scheme used to define the validations and contains the error messages (or null) for the fields.
type Message = string | null;

type MessageSchema = { [field: string]: Message; };

...

const errors: MessageSchema = {
  name: 'Use first and last name.',
  email: 'E-Mail is required.',
  phone: null, // No error message, because validators have returned true.
};

Example

<template>
  <form-container ref="form" :schema="schema" :initial="initial">
    <form slot-scope="{ fields, errors, submit }" @submit.prevent="onSubmit()">
      <fieldset>
        <label>Name</label>
        <input type="text" v-model="fields.name" />
        <span v-if="errors.name">{{ errors.name }}</span>
      </fieldset>

      <fieldset>
        <label>E-Mail</label>
        <input type="email" v-model="fields.email" />
        <span v-if="errors.name">{{ errors.email }}</span>
      </fieldset>

      <button type="submit">Sign Up</button>
    </form>
  </form-container>
</template>

<script>
  import FormContainer from 'vue-form-container';
  import * as services from './services';

  // FormContainer schema to validate fields.
  const schema = {
    name: [
      (name) => !!name.trim() || 'Name is required.'
    ],
    email: [
      (email) => !!email.trim() || 'E-Mail is required.',
      (email) => /^.+@.+\..+$/.test(email) || 'E-Mail is invalid.',
      async (email) => {
        const isRepeated = await services.isRepeatedEMail(email);
        return isRepeated || 'E-Mail is already registered.'
      }
    ]
  };

  export default {
    components: { FormContainer },
    data () {
      return {
        schema,

        // FormContainer fields initial state.
        initial: { name: '', email: '' }
      };
    },
    methods: {
      async onSubmit () {
        await this.$refs.form.validateForm();

        if (!this.$refs.form.isValid)
          return;

        console.log('submit fields', this.$refs.form.fields);
      }
    }
  };
</script>

License

Released under MIT License.

vitorluizc / vue-form-container Goto Github PK