byteclaw / forms

📋 Easily built forms in React using Hooks API

@byteclaw/forms

Easily create complex forms in React.

• Installation
• Yup compatibility
• Requirements
• Up and running example
• API
  • Form
  • Field
  • FieldError
  • ArrayField
  • ObjectField
  • ValidationError
  • useArrayField
  • useDebouncedCallback
  • useError
  • useField
  • useForm
  • useFormState
  • useObjectField
  • useParentField
  • useValues
  • createValidatorFromYup
  • validationErrorFromYupError
• Examples
• Contributions

Installation

npm install @byteclaw/forms

# or using yarn

yarn add @byteclaw/forms

Yup compatibility

This library supports Yup validation library. In order to use it please install Yup because it isn't a part of this library.

Requirements

• react >= 16.8.3

Up and running example

import { Fragment } from 'react';
import {
  ArrayField,
  Field,
  Form,
  FormProvider,
  ObjectField,
  createValidatorFromYup,
} from '@byteclaw/forms';
import * as yup from 'yup';

const validator = createValidatorFromYup(
  yup.object().shape({
    productTitle: yup.string().required(),
    images: yup
      .array()
      .of(
        yup.object().shape({
          title: yup.string().required(),
          url: yup
            .string()
            .url()
            .required(),
        }),
      )
      .required(),
    attributes: yup.object().shape({
      color: yup
        .string()
        .matches(/^#[0-9a-fA-F]{6}$/)
        .required(),
    }),
  }),
);

<Form onSubmit={async values => {}} onValidate={validator}>
  {/* global error of form */}
  <FieldError>{({ error }) => error || null}</FieldError>
  <Field name="productTitle" />
  <FieldError name="productTitle">{({ error }) => error || null}</FieldError>
  <ArrayField name="images">
    {({ value }, dispatch) => (
      <Fragment>
        {/* value can be undefined/null if is not initialized */}
        {(value || []).map((val, i) => (
          <ObjectField name={i}>
            <Field name="url" type="url" />
            <FieldError name="url">{({ error }) => error || null}</FieldError>
            <Field name="title" />
            <FieldError name="title">{({ error }) => error || null}</FieldError>
            <button onClick={() => removeItem(i)} type="button">
              Remove
            </button>
          </ObjectField>
        ))}
        <button onClick={() => dispatch({ type: 'CHANGE', value: [...value, {}] })} type="button">
          Add image
        </button>
      </Fragment>
    )}
  </ArrayField>
  <FieldError name="images">{({ error }) => error || null}</FieldError>
  <ObjectField name="attributes">
    <Field name="color" />
    <FieldError name="color">{({ error }) => error || null}</FieldError>
  </ObjectField>
  <FieldError name="attributes">{({ error }) => error || null}</FieldError>
  <FormProvider>
    {form => (
      <button disabled={form.status !== 'IDLE'} type="submit">
        Save
      </button>
    )}
  </FormProvider>
</Form>;

API

Form

Form component is a root component necessary to use Forms at all. It provides a context for all fields in a given form.

Form accepts onValidate, onSubmit and validateOnChange props along with standard attributes accepted by <form />.

• onValidate<TValues>(values?: TValues): Promise<TValues | void>
  • optional validation function
  • in case of an error please throw ValidationError provided by this library
• onSubmit<TValues>(values: TValues): Promise<void>
  • optional submit function
  • it can validate form too, in case of an error throw ValidationError provided by this library
• onChange<TValues>(values: TValues): Promise<void>
  • optional on change function
• validateOnChange
  • default is false
  • optional
  • will validate form on change

FormProvider

FormProvider is a way to connect to FormState when you need to react on something.

• children: (state: FormState) => any

Field

Field is a base component to construct simple widgets using <input /> elements. On change is debounced.

FieldError

FieldError is a base component if you want to render validation errors that are connected with a specific field or a form root.

To connect to a root of ObjectField/ArrayField/Form use it like this:

<FieldError name="">{err => JSON.stringify(err, null, ' ')}<FieldError>

Or specify name as a name that was used by Field component.

ArrayField

ArrayField is a base component to construct complex fields for array values.

ObjectField

ObjectField is a base component to construct nested objects in your form.

ValidationError

ValidationError is a way how to map errors to fields in your form.

useArrayField

useDebouncedCallback

useError

useForm

useField

useFormState

useObjectField

useParentField

useValues

createValidationErrorFromYup

validationErrorFromYupError

Examples

• Simple Form

Contributors

Michal Kvasničák 💬 💻 🎨 📖 💡 🤔 👀 ⚠️	Juraj Hríb 💬 🐛 💻 📖 🤔 👀

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT License

forms's Issues

Fix setting state on unmounted component warning

Add a way to reset a form from onSubmit handler

Maybe if we pass api to set form values to onSubmit it could be sufficient to set values to our desired values.

Fix Field type definition because now it exports exotic component

Fix reinitializing form with new initialValues

Make Field generic so it can validate props from component override (as)

Validate empty form on submit

Add an action to composite fields that allows to overwrite whole value

When Field is unmounted and then mounted again, the value is missing

On change validation does not clear itself if valid data are provided

Reproduce:

• create required field
• enter a value -> valid
• delete the value -> invalid
• enter a value -> should be valid but is invalid

Fix initialValue deletion in ArrayField

When there is an initial value for an array field and I remove it using removeItem method, then when I add new item using addItem method, I don't want to see previous value from that index.

Investigate using more complex reducer with nested fields

Basically store the whole form values state and use form reducer to dispatch actions over all fields, etc. Then just reflect the state of a field in local field state so we can easily read a field state without need to hack the state.

Propagate errors through ObjectField and ArrayField

Provide a way how to reset form to it's initial values

Investigate if yup error with inner errors is mapped correctly to all fields event nested ones

Basically if we have nested object that has few fields, we only see the error for the last one

Make Form generic so we can type onSubmit handler values

Investigate removing fields from ArrayField using REMOVE_FIELD

When I add a value to array field and then I invoke REMOVE_FIELD it still stays there. Seems like some sort of race condition where the value disappears from value array but is again added because subsequent Field component with given index as name re-adds itself automatically on mount.

Add a prop that allows to remove value from array/object field on unmount

Do not use abortEarly for yup validation

Validate on change

Add helper that converts yup validation error to inner error representation

Form valid state is invalid even if everything went successfully

Fix values in ArrayField and ObjectField on remount

Forward ref to underlying component when using Field

<Field ref={() => ...} />

should forward ref to underlying component

Fix ArrayField and ObjectField to be proper generics

Try to submit form even if it not dirty (just to run validation)