Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/spaceavocado/svelte-form

Simple Svelte form model handler and input validations.
https://github.com/spaceavocado/svelte-form

form svelte svelte3 sveltejs validation

Last synced: 3 months ago
JSON representation

Simple Svelte form model handler and input validations.

Awesome Lists containing this project

README 

        
# Svelte Form

Simple [Svelte](#https://svelte.dev) Form model handler and form fields validation library. It is designed to give maximum freedom in the actual input component construction, i.e. there are not actual build-in input components, rather examples how to build one.



To see the details code documentation, please read the [Code Documentation](https://spaceavocado.github.io/svelte-form/).



**Quick Links**

* [Webpack Setup](#webpack-setup)

* [Rollup Setup](#rollup-setup)



**Table of Content**

- [Svelte Form](#svelte-form)

  - [Installation via NPM or Yarn](#installation-via-npm-or-yarn)

  - [Webpack Setup](#webpack-setup)

  - [Rollup Setup](#rollup-setup)

  - [Essentials](#essentials)

    - [Create the Form](#create-the-form)

    - [Input Binding](#input-binding)

    - [Form State](#form-state)

    - [Form Data](#form-data)

    - [Form Field Validation](#form-field-validation)

    - [Builtin Validation Rules](#builtin-validation-rules)

      - [Required](#required)

      - [Equal](#equal)

      - [Email](#email)

      - [URL](#url)

      - [Min](#min)

      - [Max](#max)

      - [Between](#between)

      - [Regular Expression](#regular-expression)

      - [Exclude](#exclude)

      - [Include](#include)

      - [Ignore Empty](#ignore-empty)

    - [Custom Validation Rule](#custom-validation-rule)

    - [Trigger Form Validation](#trigger-form-validation)

  - [API](#api)

    - [Create Form](#create-form)

      - [Form Options](#form-options)

    - [Form Object](#form-object)

    - [Form Field Object](#form-field-object)

  - [Changes](#changes)

  - [About](#about)

  - [Contributing](#contributing)

    - [Pull Request Process](#pull-request-process)

  - [License](#license)



## Installation via NPM or Yarn

```sh

npm install -D @spaceavocado/svelte-form

```

```sh

yarn add @spaceavocado/svelte-form -D

```



## Webpack Setup

Please see the [Svelte Webpack Template](https://github.com/sveltejs/template-webpack).

Important setup in the **webpack.config.js**:

```javascript

resolve: {

  // This alias is important to prevent svelte mismatch

  // between your code, and the 3rd party components.

  alias: {

    svelte: path.resolve('node_modules', 'svelte')

  },

  extensions: ['.mjs', '.js', '.svelte'],

  mainFields: ['svelte', 'browser', 'module', 'main']

},



module: {

  rules: [

    {

      test: /\.svelte$/,

      // Do not exclude: /(node_modules)/ since the router 

      // components are located in the node_modules

      use: {

        loader: 'svelte-loader',

        options: {

          emitCss: true,

          hotReload: true

        }

      }

    }

  ]

}

```



## Rollup Setup

rollup.config.js:

```javascript

import babel from 'rollup-plugin-babel';

import resolve from 'rollup-plugin-node-resolve';

import commonjs from 'rollup-plugin-commonjs';

import svelte from 'rollup-plugin-svelte';



export default {

  input: './src/index.js',

  output: {

    file: './dist/bundle.js',

    format: 'iife'

  },

  plugins: [

    resolve(),

    commonjs({

      include: 'node_modules/**',

    }),

    svelte(),

    babel({

      exclude: 'node_modules/**',

    }),

  ]

}

```



## Essentials

Note: All code below uses ES2015+.



### Create the Form

form.svelte:

```javascript

import createForm from '@spaceavocado/svelte-form';



// An example of a form without validation

const form = createForm({

  username: '',

  password: '',

});

```

> To get more details about the createForm method, please see [Create Form](#create-form).



### Input Binding

form.svelte:

```html



import createForm from '@spaceavocado/svelte-form';

import TextInput from './input/text.svelte';



// An example of a form without validation

const form = createForm({

  username: '',

  password: '',

});



```

text.svelte:

```html



  // Props

  export let form;

  export let name;



  // Get the form field

  $: field = form.field(name);

  // Value svelte store

  $: value = field.value;

  // State svelte store, {valid: boolean, error: string}

  $: state = field.state;





  

  
{$state.error}





.input {

  .validation {

    display: none;

  }

  &.error {

    .validation {

      display: block;

    }

  }

}



```

* The state store is a derived store based on the value store, performing the input validation each time the value changes.

* The **form.field(name)** method gets the field stores, for more details see [Form Field Object](#form-field-object).



### Form State

The form state is a svelte store holding the form validation state.



form.svelte:

```javascript

import createForm from '@spaceavocado/svelte-form';



// An example of a form without validation

const form = createForm({

  username: '',

  password: '',

});



// You can directly subscribe to form state change

form.subscribe((f) => console.log(f.valid));

// or shorthand access.

console.log($form.valid)

```



> To get more details about the form, please see [Form Object](#form-object).



### Form Data

You can get the current form date anytime by calling:

```javascript

import createForm from '@spaceavocado/svelte-form';



// An example of a form without validation

const form = createForm({

  username: '',

  password: '',

});



// Get the form current data

const data = form.data();

```



### Form Field Validation

Validation functions could be passed for individual form fields:



```javascript

import createForm from '@spaceavocado/svelte-form';

import {required, email} from '@spaceavocado/svelte-form';



// An example of a form without validation

const form = createForm(

  // Form fields

  {

    username: '',

    password: '',

  },

  // Form validation - optional

  // Collection of validation rules or single rule.

  {

    username: [

      required('This field is required'),

      email('Invalid email format')

    ],

    password: required('This field is required'),

  }

);

```



**More information:**

* [Builtin Validation Rules](#builtin-validation-rules).

* [Custom Validation Rule](#custom-validation-rule).



### Builtin Validation Rules



#### Required

```javascript

import {required} from '@spaceavocado/svelte-form';



// Create new rule

const rule = required('Error message');

```



#### Equal

```javascript

import {equal} from '@spaceavocado/svelte-form';



// The value must be equal to 5

const rule = equal('Error message', 5);



// Equal can accept fn(val)->boolean as an argument for a custom

// equality matching.

const customMatcherRule = equal('Error message', (val) => {

  return val === 5;

});

```



#### Email

```javascript

import {email} from '@spaceavocado/svelte-form';



// Create new rule

const rule = email('Error message');

```



#### URL

```javascript

import {url} from '@spaceavocado/svelte-form';



// Create new rule

const rule = url('Error message');

```



#### Min

```javascript

import {min} from '@spaceavocado/svelte-form';



// The value must be 5 and more.

const rule = min('Error message', 5);

```



#### Max

```javascript

import {max} from '@spaceavocado/svelte-form';



// The value must be 5 and less.

const rule = max('Error message', 5);

```



#### Between

```javascript

import {between} from '@spaceavocado/svelte-form';



// The value must be between 5 and 10 inclusively.

const rule = between('Error message', 5, 10);

```



#### Regular Expression

```javascript

import {rx} from '@spaceavocado/svelte-form';



// The value must match custom regular expression.

const rule = rx('Error message', /\d+\.\d+/);

```



#### Exclude

```javascript

import {exclude} from '@spaceavocado/svelte-form';



// The value must not be present in the exclusion array.

const ruleA = exclude('Error message', [1, 2]);

const ruleB = exclude('Error message', ['toronto', 'new-york']);

```



#### Include

```javascript

import {include} from '@spaceavocado/svelte-form';



// The value must be present in the inclusion array.

const ruleA = include('Error message', [1, 2]);

const ruleB = include('Error message', ['toronto', 'new-york']);

```



#### Ignore Empty

This is a special rule which might be used to the ignore empty fields, i.e. any other validation rules will be tested only if the value in not empty.

```javascript

import {ignoreEmpty, url} from '@spaceavocado/svelte-form';



// An example usage

const form = createForm(

  // Form fields

  {

    website: '',

  },

  // URL validation will be tested only if the website in not empty.

  {

    website: [

      ignoreEmpty(),

      url('Invalid URL'),

    ],

  }

);



```



### Custom Validation Rule

Custom validation rule must be a function accepting a tested value, and expected to return true when valid, or error message string in not valid, e.g.:

```javascript

const invoice = (msg) => (value) => {

  if (value.match(/inv-\d+/) === null) {

    return msg;

  }

  return true;

}



// The actual rule expected by the form field, e.g. fn(val)->true|string

const rule = invoice('Invalid invoice number');

```



### Trigger Form Validation

Validation could be trigger all fields in this manner:



```javascript

import createForm from '@spaceavocado/svelte-form';

import {required, email} from '@spaceavocado/svelte-form';



// An example of a form without validation

const form = createForm(

  // Form fields

  {

    username: '',

    password: '',

  },

  // Form validation - optional

  // Collection of validation rules or single rule.

  {

    username: [

      required('This field is required'),

      email('Invalid email format')

    ],

    password: required('This field is required'),

  }

);



// Trigger validation of all fields

form.validate();

```



## API

To see the details code documentation, please read the [Code Documentation](https://spaceavocado.github.io/svelte-form/)



### Create Form

```javascript

import createForm from '@spaceavocado/svelte-form';



// Please see the opts below.

const formOpts = {};



// Please see the Form object for details on returned object

const form = createForm(

  // Form fields

  {

    username: '',

    password: '',

  },

  // Form validation - optional

  // Collection of validation rules or single rule.

  {

    username: [

      required('This field is required'),

      email('Invalid email format')

    ],

    password: required('This field is required'),

  },

  // Form options - optional

  formOpts,

);

```



#### Form Options

| Property           | Description                                                       | Type    |

| :----------------- | :---------------------------------------------------------------- | :------ |

| onCreateValidation | Validate form fields when the form is created. Defaults to false. | boolean |



### Form Object

| Property  | Description                                                                                                    | Type     |

| :-------- | :------------------------------------------------------------------------------------------------------------- | :------- |

| subscribe | Svelte store, context {valid: boolean}.                                                                        | function |

| field     | Get form field observable value and state. Signature fn(key), returns [Form Field Object](#form-field-object). | function |

| data      | Get all form fields data. Signature fn().                                                                      | function |



### Form Field Object

| Property | Description                                             | Type     |

| :------- | :------------------------------------------------------ | :------- |

| value    | Svelte store, context: mixed value.                     | function |

| state    | Svelte store, context: {valid: boolean, error: string}. | function |



## Changes

To see the changes that were made in a given release, please lookup the tag on the releases page. The full changelog could be seen here [changelog.md](https://github.com/spaceavocado/svelte-form/blob/master/changelog.md)



## About

This project is mainly to explore and test [Svelte](#https://svelte.dev) in SPA realm. Any feedback, contribution to this project is welcomed.



The project is in a beta phase, therefore there might be major changes in near future, the annotation should stay the same, though.



## Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.



### Pull Request Process

1. Fork it

2. Create your feature branch (git checkout -b ft/new-feature-name)

3. Commit your changes (git commit -am 'Add some feature')

4. Push to the branch (git push origin ft/new-feature-name)

5. Create new Pull Request

> Please make an issue first if the change is likely to increase.



## License

Svelte Router is released under the MIT license. See [LICENSE.txt](https://github.com/spaceavocado/svelte-router/blob/master/LICENSE.txt).