formula-one

formula-one is a library which makes it easier to write type-safe forms with validations and complex inputs.

![Yarn Test](https://github.com/flexport/formula-one/actions/workflows/test.yml)

A minimal example, with no validation

Edit the working example on CodeSandbox

``jsx // @flow strict

import React from "react"; import {Form, Field, ObjectField, FeedbackStrategies} from "formula-one";

type Person = { name: string, age: string, faction: "Empire" | "Rebels", };

const EMPTY_PERSON: Person = { name: "", age: "", faction: "Empire", };

export default function SimpleExample() { return (


              initialValue={EMPTY_PERSON}
        onSubmit={person => console.log("Submitted", person)}
      >
        {(link, onSubmit) => (
          
            {links => (
              <>
                
                  {(value, errors, onChange) => (
                    
                      Name

                                              type="text"
                        value={value}
                        onChange={e => onChange(e.target.value)}
                      />
                    
                  )}
                
                
                  {(value, errors, onChange) => (
                    
                      Age

                                              type="text"
                        onChange={e => onChange(e.target.value)}
                        value={value}
                      />
                    
                  )}
                
                
                  {(value, errors, onChange) => (
                    
                      Faction

                                              onChange={e => onChange(e.target.value)}
                        value={value}
                      >
                        
                        
                      
                    
                  )}
                
                

                  
                

              
            )}
          
        )}


  );
}


Philosophy

formula-one helps you write forms in React by managing the state of your form and ensuring your inputs are the right type. It does this by introducing a new abstraction, called a _Field_. A _Field_ wraps some value and provides a way to render and edit that value. A simple _Field_ might wrap a string, which displays and edits its value through an . A more complex value, such as a date and time might be displayed as an ISO 8601 string and be edited through a calendar input.

Fields are specified using the component, which wraps your input using a render prop. It provides the value, errors, onChange, and onBlur handlers, which should be hooked up to your input.

Individual Fields are aggregated into objects and arrays using the and components. These components enable you to build forms with multiple fields.

In formula-one, all of the form's state is held in the

 component, and communicated to its internal Fields via opaque props called links. These links contain all of the data and metadata used to render an input and its associated errors.
Validations
$3

formula-one provides an api for specifying validations on Fields. Each _Field_ exposes a validation props, which has the type T => Array for a Field of type T. Each string represents an error message, and the empty array indicates no errors.

An example of a Field which doesn't allow empty strings:

Edit the working example on CodeSandbox

`jsx function noEmptyStrings(s: string): Array { if (s === "") { return ["Cannot be empty"]; } return []; }

{(value, errors, onChange) => ( <>

Name


                  type="text"
          value={value}
          onChange={e => onChange(e.target.value)}
        />
        {errors ? (
          
            {errors.map(e => (
              {e}

            ))}
          

        ) : null}
      
    
  )}
;

$3

In addition to tracking errors and validating when inputs change, formula-one tracks metadata to help you decide whether you should show errors to your user. allows you to specify a strategy for when to show errors.

Some base strategies are exported as fields on the FeedbackStrategies object. Here is a table of the strategies and their behavior.

| Strategy identifier | Strategy Behavior | | ---------------------------------------------- | ------------------------------------------------------------------------------------ | |FeedbackStrategies.Always| Always show errors (default) | |FeedbackStrategies.Touched| Show errors for fields which have been touched (changed or blurred) | |FeedbackStrategies.Blurred| Show errors for fields which have been blurred | |FeedbackStrategies.Changed| Show errors for fields which have been changed | |FeedbackStrategies.ClientValidationSucceeded| Show errors for fields which have had their validations pass at any time in the past | |FeedbackStrategies.Pristine| Show errors when the form has not been modified | |FeedbackStrategies.Submitted | Show errors after the form has been submitted |

These simple strategies can be combined by using the and, or, and not functions also on the FeedbackStrategies object, as follows:

`js import {FeedbackStrategies} from "formula-one"; const {Changed, Blurred, Submitted, or, and} = FeedbackStrategies; const strategy = or(and(Changed, Blurred), Submitted);`

`$3`

To specify multiple validations for a single field, simply run the validations in sequence and serialize their errors into a single array.

Edit the working example on CodeSandbox

`jsx function validate(s: string): Array { return [noEmptyStrings, mustHaveNumbers, noLongStrings].flatMap(validation => validation(s) ); }`

`$3`

Both and allow a validation to be specified. You can use the component to extract the errors from the link.

`$3`

Even inputs which are complex (e.g. a datepicker) can be wrapped in a wrapper, but validations are tracked at the field level, so you won't be able to use formula-one to track changes and validations below the field level. For example, you can't represent a validation error for _just the day part_ of a date if you only have a single wrapping a datepicker. Instead, the error will be associated with the entire date.

`Common use cases`

`$3`

Often, you may want to edit a list of items in a form. formula-one exposes an aggregator called , which allows you to manipulate a list of Fields.

For example, imagine you have a form for a person, who has a name, but also some number of pets, who each have their own name.

Edit the working example on CodeSandbox

`jsx type Person = { name: string, pets: Array<{ name: string, }>, };

const emptyPerson: Person = { name: "", pets: [], };

export default function () { return (


              initialValue={emptyPerson}
        onSubmit={p => console.log("Submitted", p)}
      >
        {(link, onSubmit) => (
          
            {links => (
              <>
                
                  {(value, errors, onChange) => (
                    
                      Name

                                              type="text"
                        onChange={e => onChange(e.target.value)}
                        value={value}
                      />
                    
                  )}
                
                
                  {(links, {addField}) => (
                    
                      {links.map((link, i) => (
                        
                          {link => (
                            
                              {(value, errors, onChange) => (
                                
                                  Pet #{i + 1}
                                                                      type="text"
                                    value={value}
                                    onChange={e => onChange(e.target.value)}
                                  />
                                

                              )}
                            
                          )}
                        
                      ))}
                      {links.length === 0 ? "No pets :(" : null}
                                              onClick={() => addField(links.length, {name: ""})}
                      >
                        Add pet
                      
                    

                  )}
                
                
                  
                

              
            )}
          
        )}


  );
}

exposes both an array of links to the array elements, but also an object containing mutators for the array:

- addField(index: number, value: E): Add a field at a position in the array -addFields(spans: $ReadOnlyArray>): Add multiple fields to an array -removeField(index: number): Remove a field at a position in array -filterFields(predicate: (item: E, index: number) => boolean): Remove multiple fields from an array -modifyFields({insertSpans: $ReadOnlyArray>, filterPredicate: (item: E, index: number) => boolean}): Simultaneously add and remove fields from an array -moveField(fromIndex: number, toIndex: number): Move a field in an array (preserves metadata for the field)

where Span is a range to be inserted at an index: [number, $ReadOnlyArray].

`$3`

Oftentimes, when you need to wrap a component which has a button you will use for submission, you can simply wrap that component with your

element. The

 does not render any elements, so it will not affect your DOM hierarchy.
Example:

`jsx {(link, handleSubmit) => ( Submit]}> ... )}`

`$3`

Sometimes a change in one field has to be reflected in another field. and have a prop customChange to allow this. It will be called when a child Field changes, and by returning a non-null result you can override the whole Currently, no metadata is preserved (all fields are marked changed, blurred, and touched) if a customChange function is used.

The API is:

`jsx // Override nextValue by returning a non-null result customChange: (prevValue: T, nextValue: T) => null | T;`

Edit the working example on CodeSandbox

`jsx const SHIPS = { "X-Wing": {faction: "Rebels", name: "X-Wing"}, "Y-Wing": {faction: "Rebels", name: "Y-Wing"}, "TIE Fighter": {faction: "Empire", name: "TIE Fighter"}, "TIE Defender": {faction: "Empire", name: "TIE Defender"}, };

type Person = { name: string, age: string, faction: "Empire" | "Rebels", ship: string, };

export default function CustomChange() { return (


              initialValue={EMPTY_PERSON}
        onSubmit={person => console.log("Submitted", person)}
      >
        {(link, onSubmit) => (
          
            {links => (
              <>
                {/.../}
                {/.../}
                

                  
                

              
            )}
          
        )}


  );
}

$3

Oftentimes, you will want to show errors from an external source (such as the server) in your form alongside any client-side validation errors. These can be passed into your

component using the externalErrors

 prop.
These errors must be in an object with keys representing the path to the field they should be associated with. For example, the errors:

`js const externalErrors = { "/": "User failed to save!", "/email": "A user with this email already exists!", };`

could be used in this form:

`jsx {(link, handleSubmit) => ( <> {links => ( <> )} {({shouldShowErrors, flattened}) => shouldShowErrors ? (


              {flattened.map(errorMessage => (
                {errorMessage}

              ))}


Advanced usage
$3

Additional information is available in an object which is the last argument to the

, , , and components' render props. This object contains the following information:

| key | type | description | | ----------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | touched |boolean| Whether the field has been touched (blurred or changed) | | changed |boolean| Whether the field has been changed | | blurred |boolean| Whether the field has been blurred | | shouldShowErrors |boolean| Whether errors should be shown according to the current feedback strategy | | unfilteredErrors |$ReadOnlyArray | All validation errors for the current field. (This differs from the errors argument in , since the errors argument in will be empty if shouldShowErrorsis false) | | valid |boolean| Whether the field (and its children) pass their validations (NOTE: only client errors are considered!) | | asyncValidationInFlight |boolean| Whether there is an asynchronous validation in progress for this field | | value |T | The current value for this field. (This will always match the value argument to ) |

An example of how these data could be used:

`jsx {(link, handleSubmit, {valid}) => ( <> {(value, errors, onChange, onBlur, {changed}) => ( Name type="text" value={value} onChange={onChange} onBlur={onBlur} /> {changed ? "(Modified)" : null} )} )}`

`$3`

Sometimes, you need to have multiple submission buttons and need to know which button was clicked in your onSubmit prop callback. This can be achieved by passing additional information as an argument to the handleSubmit argument to your

's render prop. This argument will be passed to your onSubmit prop callback as a second argument. If your onSubmit prop callback is typed to make this extra data mandatory, the inner handleSubmit

 callback will require that data.
Example:

`jsx function handleSubmit(value: User, saveOrSubmit: "save" | "submit") { if (saveOrSubmit === "save") { // ... } else if (saveOrSubmit === "submit") { // ... } }

{(link, handleSubmit) => ( <>


    
  )}
;

$3

It is easy to submit a formula-one form using the handleSubmit argument provided to

's render prop, but sometimes you need to submit a from outside. This is possible using the submit() method available on along with a React ref to that element. This submit() method can also receive additional user-specified information, as stated above.

`jsx function handleSubmit(value) { / ... / }

class MyExternalButtonExample extends React.Component { form: null | React.Element;

constructor(props: Props) { super(props);

this.form = null; this.handleSubmitClick = this.handleSubmitClick.bind(this); }

handleSubmitClick() { if (this.form != null) { this.form.submit(); } }

render() { return (


                  ref={f => {
            this.form = f;
          }}
          onSubmit={handleSubmit}
        >
          {link => }


    );
  }
}


Frequently Asked Questions
$3

Normally, after the initial render, a

component will ignore changes to its initialState prop. This is necessary because the

 component tracks metadata in addition to the any updates to the value of the form, and it must maintain that data as the user edits the form. If you want to start over with a new initial state and count all fields as unchanged and unblurred, you can provide a

key prop to your . When this key changes, React will discard the state of your form and will be initialized with the provided initialState`.

formula-one

formula-one is a library which makes it easier to write type-safe forms with validations and complex inputs.

![Yarn Test](https://github.com/flexport/formula-one/actions/workflows/test.yml)

A minimal example, with no validation

Edit the working example on CodeSandbox

``jsx // @flow strict

import React from "react"; import {Form, Field, ObjectField, FeedbackStrategies} from "formula-one";

type Person = { name: string, age: string, faction: "Empire" | "Rebels", };

const EMPTY_PERSON: Person = { name: "", age: "", faction: "Empire", };

export default function SimpleExample() { return (


              initialValue={EMPTY_PERSON}
        onSubmit={person => console.log("Submitted", person)}
      >
        {(link, onSubmit) => (
          
            {links => (
              <>
                
                  {(value, errors, onChange) => (
                    
                      Name

                                              type="text"
                        value={value}
                        onChange={e => onChange(e.target.value)}
                      />
                    
                  )}
                
                
                  {(value, errors, onChange) => (
                    
                      Age

                                              type="text"
                        onChange={e => onChange(e.target.value)}
                        value={value}
                      />
                    
                  )}
                
                
                  {(value, errors, onChange) => (
                    
                      Faction

                                              onChange={e => onChange(e.target.value)}
                        value={value}
                      >
                        
                        
                      
                    
                  )}
                
                

                  
                

              
            )}
          
        )}


  );
}


Philosophy

Fields are specified using the component, which wraps your input using a render prop. It provides the value, errors, onChange, and onBlur handlers, which should be hooked up to your input.

Individual Fields are aggregated into objects and arrays using the and components. These components enable you to build forms with multiple fields.

In formula-one, all of the form's state is held in the

 component, and communicated to its internal Fields via opaque props called links. These links contain all of the data and metadata used to render an input and its associated errors.
Validations
$3

An example of a Field which doesn't allow empty strings:

Edit the working example on CodeSandbox

`jsx function noEmptyStrings(s: string): Array { if (s === "") { return ["Cannot be empty"]; } return []; }

{(value, errors, onChange) => ( <>

Name


                  type="text"
          value={value}
          onChange={e => onChange(e.target.value)}
        />
        {errors ? (
          
            {errors.map(e => (
              {e}

            ))}
          

        ) : null}
      
    
  )}
;

$3

Some base strategies are exported as fields on the FeedbackStrategies object. Here is a table of the strategies and their behavior.

These simple strategies can be combined by using the and, or, and not functions also on the FeedbackStrategies object, as follows:

`js import {FeedbackStrategies} from "formula-one"; const {Changed, Blurred, Submitted, or, and} = FeedbackStrategies; const strategy = or(and(Changed, Blurred), Submitted);`

`$3`

To specify multiple validations for a single field, simply run the validations in sequence and serialize their errors into a single array.

Edit the working example on CodeSandbox

`jsx function validate(s: string): Array { return [noEmptyStrings, mustHaveNumbers, noLongStrings].flatMap(validation => validation(s) ); }`

`$3`

Both and allow a validation to be specified. You can use the component to extract the errors from the link.

`$3`

`Common use cases`

`$3`

Often, you may want to edit a list of items in a form. formula-one exposes an aggregator called , which allows you to manipulate a list of Fields.

For example, imagine you have a form for a person, who has a name, but also some number of pets, who each have their own name.

Edit the working example on CodeSandbox

`jsx type Person = { name: string, pets: Array<{ name: string, }>, };

const emptyPerson: Person = { name: "", pets: [], };

export default function () { return (


              initialValue={emptyPerson}
        onSubmit={p => console.log("Submitted", p)}
      >
        {(link, onSubmit) => (
          
            {links => (
              <>
                
                  {(value, errors, onChange) => (
                    
                      Name

                                              type="text"
                        onChange={e => onChange(e.target.value)}
                        value={value}
                      />
                    
                  )}
                
                
                  {(links, {addField}) => (
                    
                      {links.map((link, i) => (
                        
                          {link => (
                            
                              {(value, errors, onChange) => (
                                
                                  Pet #{i + 1}
                                                                      type="text"
                                    value={value}
                                    onChange={e => onChange(e.target.value)}
                                  />
                                

                              )}
                            
                          )}
                        
                      ))}
                      {links.length === 0 ? "No pets :(" : null}
                                              onClick={() => addField(links.length, {name: ""})}
                      >
                        Add pet
                      
                    

                  )}
                
                
                  
                

              
            )}
          
        )}


  );
}

exposes both an array of links to the array elements, but also an object containing mutators for the array:

where Span is a range to be inserted at an index: [number, $ReadOnlyArray].

`$3`

Oftentimes, when you need to wrap a component which has a button you will use for submission, you can simply wrap that component with your

element. The

 does not render any elements, so it will not affect your DOM hierarchy.
Example:

`jsx {(link, handleSubmit) => ( Submit]}> ... )}`

`$3`

The API is:

`jsx // Override nextValue by returning a non-null result customChange: (prevValue: T, nextValue: T) => null | T;`

Edit the working example on CodeSandbox

type Person = { name: string, age: string, faction: "Empire" | "Rebels", ship: string, };

export default function CustomChange() { return (


              initialValue={EMPTY_PERSON}
        onSubmit={person => console.log("Submitted", person)}
      >
        {(link, onSubmit) => (
          
            {links => (
              <>
                {/.../}
                {/.../}
                

                  
                

              
            )}
          
        )}


  );
}

$3

Oftentimes, you will want to show errors from an external source (such as the server) in your form alongside any client-side validation errors. These can be passed into your

component using the externalErrors

 prop.
These errors must be in an object with keys representing the path to the field they should be associated with. For example, the errors:

`js const externalErrors = { "/": "User failed to save!", "/email": "A user with this email already exists!", };`

could be used in this form:

`jsx {(link, handleSubmit) => ( <> {links => ( <> )} {({shouldShowErrors, flattened}) => shouldShowErrors ? (


              {flattened.map(errorMessage => (
                {errorMessage}

              ))}


Advanced usage
$3

Additional information is available in an object which is the last argument to the

, , , and components' render props. This object contains the following information:

An example of how these data could be used:

`$3`

 callback will require that data.
Example:

`jsx function handleSubmit(value: User, saveOrSubmit: "save" | "submit") { if (saveOrSubmit === "save") { // ... } else if (saveOrSubmit === "submit") { // ... } }

{(link, handleSubmit) => ( <>


    
  )}
;

$3

It is easy to submit a formula-one form using the handleSubmit argument provided to

`jsx function handleSubmit(value) { / ... / }

class MyExternalButtonExample extends React.Component { form: null | React.Element;

constructor(props: Props) { super(props);

this.form = null; this.handleSubmitClick = this.handleSubmitClick.bind(this); }

handleSubmitClick() { if (this.form != null) { this.form.submit(); } }

render() { return (


                  ref={f => {
            this.form = f;
          }}
          onSubmit={handleSubmit}
        >
          {link => }


    );
  }
}


Frequently Asked Questions
$3

Normally, after the initial render, a

component will ignore changes to its initialState prop. This is necessary because the

 component tracks metadata in addition to the any updates to the value of the form, and it must maintain that data as the user edits the form. If you want to start over with a new initial state and count all fields as unchanged and unblurred, you can provide a

key prop to your . When this key changes, React will discard the state of your form and will be initialized with the provided initialState`.

formula-one

Dist Tags

formula-one

A minimal example, with no validation

Philosophy

Validations

$3

$3

$3

$3

$3

Common use cases

$3

$3

$3

$3

Advanced usage

$3

$3

$3

Frequently Asked Questions

$3

formula-one

Dist Tags

formula-one

A minimal example, with no validation

Philosophy

Validations

$3

$3

$3

$3

$3

Common use cases

$3

$3

$3

$3

Advanced usage

$3

$3

$3

Frequently Asked Questions

$3

`$3`

`$3`

`$3`

`Common use cases`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Common use cases`

`$3`

`$3`

`$3`

`$3`