formo

Form state management

Usage (basic example)

import formo from 'formo'

const MyFormoComponent = formo(
  class MyFC extends React.Component {
    render() {
      const {
        email, password,
        form: { isValid, isChanged }
      } = this.props
      const submitEnabled = isChanged && isValid

      return (
        <div>
          <input
            type='email'
            value={email.value || ''}
            onChange={e => email.update(e.target.value)}
          />
          {email.touched && email.validationErrors.map(error => (
            <div className='error'>{error}</div>
          )}
          <input
            type='password'
            value={password.value || ''}
            onChange={e => password.update(e.target.value)}
          />
          <input type='submit' value='submit' disabled={!submitEnabled} />
        </div>
      )
    }
  }
)

const fields = {
  email: {},
  password: {}
}

const validations = {
  email: {
    invalidEmail: v => validEmailRegex.test(v)
  }
}

export default class MyComponent {
  render() {
    return <MyFormoComponent fields={fields} validations={validations} />
  }
}

Motivation and guiding principles

• avoid repeating common tasks among different form, such as validation logic, computing "dirtiness" state, enabling submit button, showing errors only if X, etc.
• it should be independent from rendering (not tied to a specific set of UI components)
• it should be independent from the state management framework (not tied to redux, mobx, etc.)
• it should be easy to use as-is, as a stateful component, and easy to integrate with any state management framework

API

Create a "formo component"

import formo from 'formo'

class MyComponent extends React.Component {
  // ...
}

export default formo(MyComponent)

From this component, you'll have access to the complete form state via props. This includes current values, validity, and other useful meta info such as "touched", "changed", etc. See a comprehensive list in the tables below.

configure a "formo component"

A "formo component" can be configured through props with a set of fields and validations to apply.

import MyFormoComponent from './MyFormoComponent'

  // ...

  render() {
    // `validations` and `onChange` are optional
    return (
      <MyFormoComponent
        fields={fields}
        validations={validations}
        onChange={onChange}
      />
    )
  }

  // ...

props API

name | required | type | description ---|---|---|--- fields | required | dict(FieldName, Field) | Configure form fields validations | | dict(FieldNameOrForm, dict(validationName, Validations)) | Optionally configure form-level and field-level validations onChange | | function<Value> | Optionally provide an onChange callback, will be called with the new values after every change

FieldName: a string representing a field, e.g. "email".

Field: an object in the form:

{
  value: any,
  initialValue: any,
  active: ?boolean,
  touched: ?boolean
}

FieldNameOrForm = FieldName | 'form': form-level validations are specified using the special string "form".

Validations: a dict(string, function) with each function, returning a Boolean.

Each function is called with two arguments (field value and all form values) if applied to a field, with a single value (all form values) if it is applied at form-level.

In other words, a validation function should be treated like a test that the field or the form should pass.

formo will list the failed validation function names in the validationErrors array.

Validity for single fields and for the global form is computed based on presence (absence) of these errors.

fields example

fields = {
  email: {
    value: cookie.email
  },
  password: {},
  repeatPassword: {},
  foo: {
    initialValue: true
  },
  bar: {
    initialValue: false
  }
}

validations example

validations = {
  password: {
    minLength: value => value.length > 8,
    numeric: value => value.test(/\d/)
  },
  repeatPassword: {
    passwordMatch: (repeatPassword, { password }) => repeatPassword === password
  },
  form: {
    atLestOneFooOrBar: values => !value.foo && !value.bar
  }
}

Use form values from a "formo component"

Formo component props api

A formo component receives via props:

• form-level values and derived properties, via the form prop
• for each field, field-level value and derived properties, via the [field] prop.

Form-level props

type | name/usage | description ---|---|--- function | form.clearValues() | Sets every field value in the form to field.initialValue || undefined. The input below should be aware and handle undefined as controlled anyway. function | form.touchAll() | Sets every field as "touched". Useful if we have a validation UI rendering logic similar to touched && errors && renderErrors() and we want to force errors rendering after a certain event (e.g. user clicks on "submit") boolean | form.isChanged | Is any field changed? boolean | form.isValid | Is the form as a whole "valid" (no validation errors)? list(string) | form.validationErrors | validations failing

Form-level prop usage example

// ...
render() {
  const submitEnabled = this.props.form.isValid && this.props.form.isChanged;
  const errors = map(this.props.form.validations, err => <Error>{err}</Error>)
  return (
    // ...
    {errors}
    <input type='submit' value='Submit' disabled={!submitEnabled} />
    // ...
  )
}
// ...

Field-level props

type | name/usage | description ---|---|--- any | [field].value | Always == value || initialValue || undefined. The input below should be aware and handle undefined as controlled anyway any | [field].initialValue | initialValue provided in form config for the field, if any function(any) | [field].update(newValue) | Updates a field value. Typically passed to an input onChange boolean | [field].active | Whether the field is currently "active". It is guaranteed to be exclusive (a single field is active at any time. If multiple fields are marked as "active" in config, only the first one is considered active) function | [field].setActive() | Set the field as "active" function | [field].unsetActive() | Set the field as "non active". Also updates touched accordingly boolean | [field].touched | true if input has been unsetActive() in the past (typically after a blur, or, as always, if the field is configured as touched=true in config) function | [field].clear() | Set field value to initialValue || undefined boolean | [field].isChanged | true if input value is the same as initialValue (or "adequately equal") list(string) | form.validationErrors | validations failing any | [field].[<any other key>] | Any other field key provided in form config is just passed down function(string, any) | [field].set('prop', value) | Any other field key can be changed using .set

Field-level prop usage example

// ...
render() {
  const email = this.props.email;
  const className = cx({
    active: email.active,
    error: email.touched && !email.isValid
  })
  return (
    <input
      type='email'
      value={email.value || ''}
      className={className}
      onFocus={email.setActive}
      onBlur={email.unsetActive}
      onChange={e => email.update(e.target.value)}
    />
  )
}
// ...