svelte-formula

Svelte Formula

Formula is a zero-configuration reactive form library for Svelte, currently in early development.

This library uses HTML form attributes to do validation, and works with the localised message from the browser.

Install Instructions

npm i svelte-formula

Usage

To use Formula, create the directive and store values by calling the formula() method in the library, this returns the form action and the available stores.

Options

While the library is zero-configuration it does support options which can be passed as an object to the formula constructor method.

Options	Type	Description
locale	String	Optional locale for id sorting when using multiple values
validators	Object	An object containing custom validators for fields
formValidators	Object	An object containing custom validators for the form

Example

The form action can be used with any element and not just <form> elements - it checks for all child form elements that have a name attribute and return some kind of validity. If used with a form element it will provide values on submit, as well as the current value of the form.

<script>
  import { formula } from 'svelte-formula'

  const { form, formValues, submitValues, validity, touched, formValid } = formula();

  $: console.log($formValues);
  $: console.log($submitValues);

  function handleSubmit(e) {
    e.preventDefault();
  }


</script>

<form use:form on:submit={handleSubmit}>
  <div class='form-field'>
    <label for='username'>Username</label>
    <input type='email' id='username' name='username' required />
    <span hidden={$validity?.username?.valid}>{ validity?.username?.message }</span>
  </div>
  <div class='form-field'>
    <label for='password'>Password</label>
    <input type='password' id='password' name='password' required minlength='8' />
    <span hidden={$validity?.password?.valid}>{ validity?.password?.message }</span>
  </div>

  <button disabled={!$formValid}>Save</button>
</form>

Stores

dirty

A store that updates when fields are marked as dirty - contains an Object with key/value of name and Boolean, fields where the user triggers a blur event, and the value has been changed from the original value.

formValues

The formValues store can be subscribed to and will emit every time the user types into, or blurs off from a field. The value is a Object that contains a key/value map of all form fields with the key being the name property of the element

formValidity

A store that contains a key/value Object of errors on the form when using formValidators - unlike validity this only contains a key and string value that is any message from the validator.

isFormValid

A store that is a single Boolean value if the form is currently valid or not - this only emits when the form validity changes

submitValues

Similar to the formValues object, the subscription only emits when a form submit event occurs, and only emits when using a <form> element

touched

A store that updates when fields are marked as touched - contains an Object with key/value of name and Boolean, fields are added to the store as they receive a focus event

validity

A store that contains a key/value Object where again the key is the name property. The value is another object with the following properties

• valid - Boolean - If the field is valid
• invalid - Boolean - if the field is invalid
• message - String - The message returned from the HTML validity
• errors - Object - A map of errors that are true returned by the Constraint Validation API, or from custom validators in the options.

Custom Field Validations

While Formula is zero-config and uses validations set on the HTML5 elements, it's also possible to provide custom validations via the validations option passed to formula on initialisation.

First provide the name of the field as a key, and the value as an Object - each object contains further keys per error, and a function that does the validation - the result should be a string if it fails, or null if it passes.

Custom validation will always be added to the errors object, however the message - HTML validations will always take precedence over custom validations (e.g. <input required> message will always be before your custom message)

Custom validators also support multi-value fields, but in this case an id must be set on each field to provide uniqueness (such as an index value)

Example

<script>
  import { formula } from 'svelte-formula';

  const { form, validity } = formula({
    validators: {
      username: {
        inCompanyDomain: (value: string) => value.includes('@ourdomain.com') ? null : 'Your username must contain an @ourdomain.com email'
      },
      invoiceIds: {
        validInvoiceId: (values: string[]) => values.every(value => value.startsWith('INV-')) ? null : 'Your invoice IDs must start with INV-'
      }
    }
  });
</script>
<form use:form>
  <label for='signup-username'>Username</label>
  <input type='email' name='username' id='signup-username' required minlength='8' />
  <div hidden={$validity?.email?.valid}>{$validity?.email?.message}</div>

  <input type='text' name='invoiceIds' id='1' />
  <input type='text' name='invoiceIds' id='2' />
  <input type='text' name='invoiceIds' id='3' />
</form>

Form Level Validation

Form level validations can also be provided using formValidators - these validators are passed the entire set of values and allow for validation across different values (like password matching, or ensuring a selection is made in one field based on another form field condition)

<script>
  import { formula } from 'svelte-formula';

  const { form, formValidity } = formula({
    formValidators: {
      passwordsMatch: (values) => values.password === values.passwordMatch ? null : 'Your passwords must match'
    }
  })
</script>
<form use:form>
  <input type='password' name='password' required minlength='8'>
  <input type='password' name='passwordMatch' required minlength='8'>
  <div hidden={!$formValidity?.passwordsMatch}>{$formValidity?.passwordsMatch}</div>
</form>

Roadmap

Field Type Support

• Support Basic Input fields (text, number, password, email, url) as text values
  • Support multiple named fields with unique id attributes, with an array of results sorted by ID alphabetically
  • Return correct value type for fields (return number as Number value)
• Support Select Fields
  • Support Multiple Select Fields
• Support Radio Fields
• Support Checkbox Fields
  • Support Multiple Checkbox Fields
• Support the Range input
• Support the Color input
• Support the Date / Time / DateTime inputs
• Support the File input

Validation

• Custom field-level validation via formula options
• Custom form-level validation via formula options

Other Items

• Add Unit Tests
• Add full documentation

Icon made by Eucalyp from flaticon.com

Changelog

[0.2.0] 2021-02-15

Changed

• formValid now isFormValid

Added

• Support for custom field-level validators via the validators property of the formula options. Validators are provided as an object - the key is the name of the fields, and the value is another object containing the validators. Each validator is has a key that is the name of the validation and a function that returns a string if the validation fails or null if it passes. The string message is used to display the message, the key is added to the errors object in validity

  <script>
  import { formula } from 'svelte-formula'
  import { calculateStrong } from '../libs/password'
   const { form, formValues, submitValues, validity, touched, dirty, formValid } = formula({
        validators: {
            password: {
              isStrong: (value: string) => calculateStrong(value) ? null : 'Your password is too weak'
            },
            'invoice-ids': {
              invoicePrefix: (values: string[]) => values.every(value => value.startsWith('INV-')) ? null : 'Your invoice IDs must all begin with INV-'
            }
        }
  });
  </script>
  
  ...
  <input type='password' name='password' required minlength='8' class:error={$touched?.password && $validity?.username?.invalid}/>
  <div hidden={$validity?.password?.valid}>{$validity?.password?.message}</div>
  <div hidden={$validity?.password?.errors?.isStrong}>You have a strong password!</div>
  ...
  
  <input type='text' id='invoice-1' name='invoice-ids' />
  <input type='text' id='invoice-2' name='invoice-ids' />
  <input type='text' id='invoice-3' name='invoice-ids' />
   <div hidden={$validity?.['invoice-ids']?.valid}>{$validity?.['invoice-ids']?.message}</div>
  

• Support for custom form-level validators via the formValidators property of the formula options. Validators are provided as an object - Each validator has a key that is the name of the validation, and a function that returns a string if the validation fails or null if it passes. The error message are available via the formValidity store.

  <script>
  import { formula } from 'svelte-formula'
  const { form, submitValues, submitValidity, formValid } = formula({
    formValidators: {
      passwordsMatch: (values) => values.password === values.passwordMatch ? null : 'Your passwords must match'
    }
  })
  </script>
  
  <input type='password' name='password' required minlength='8'>
  <input type='password' name='passwordMatch' required minlength='8'>
  <div hidden='{!$submitValidity?.passwordsMatch}'>{$submitValidity?.passwordsMatch}</div>
  

Fixed

• Correctly pass options to form creation