brief-form v5.2.0

brief-form

brief-form is a small React based form management tool. The main package API is useFormData hook which provides all necessary form data and service methods. It provides approach to manage form data but it's not bound to any particular UI implementation, so library can be used in web React apps or in the React Native applications.

Quick usage example

import React, { memo } from 'react'
import { FormProvider, useFormData } from 'brief-form'

type MyForm = {
  age: number
  name: string
  happy: boolean
}

const InitialValue = {
  age: 37,
  name: 'Andrey',
  happy: true
}

export const SomeFormComponent = memo(() => {
  const {
    isDirty,  // form value was changed
    isValid,  // form is valid
    validate, // method for form validation
    reset,    // reset form state
    Field,    // Field component to render UI input
    Form,     // Form component
    config    // form configuration object
  } = useFormData<MyForm>()

  return <FormProvider fieldRenderer={FieldRenderer}>
    <Form config={config}>
      <Field
        required
        name="name"
        label="Name"
        input={TextInput}
        validator={(v) => (v.length < 3 ? 'Name too short' : undefined)}
        inputProps={{}}
      />
      <Field 
        name="age" 
        label="Age" 
        input={NumberInput} 
        inputProps={{ type: 'integer' }} 
      />
      <Field 
        name="happy" 
        label="Happy?" 
        input={CheckBoxInput} 
        inputProps={{}} 
      />
    </Form>
  </FormProvider>
})

Let's dig into more details!

Form

Form is a container component holding all UI fields. The only required parameter is config. It's value returned from useFormData hook. As were mentioned before, library doesn't contain any UI implementations, so we should explicitly define which UI component should render form UI field (basically it should render label, input and error). We can do it through fieldRenderer Form parameter to set renderer individually for each form. Or we can use FormProvider component and set up this renderer globally for all nested forms.

<Form config={config} fieldRenderer={UIField}>
</Form>

FormProvider

FormProvider gives us ability to perform global form setup.

fieldRenderer parameter accepts React component to be used for rendering form UI field.

crashIfRequiredFieldDoesNotHaveValidator defines whether form should crash if it contains any fields marked as required but not providing validator function. In most cases it helps more quickly find required inputs without validators during development. Basically required field property just marks fields as required (e.g. field renderer can draw asterisk near label for these fields). Validator function contains logic defining whether field "empty" or "filled". For example we can think about integer input as empty if its value is 0, but for more complex inputs things may be more complex and ambiguous. That's why we need custom validator here.

We would recommend always use FormProvider component to reduce amount of boilerplate code.

useFormData

This hook is the main library API.

  const formData = useFormData<MyFormType>(initialData, initialErrors)

It expects generic parameter (MyFormType) describing form value shape and two arguments - initial form data (required) and initial form errors (optional).

Let's take a look at what formData contains:

We highly recommend to use Form and Field components returned from this hook, as they are already bound to form type passed to hook.

Field

This component is the main form field data management piece. Its parameters are listed below:

Field input component

It were mentioned above, input should implement FormInputProps<V, P> interface where V is a input value type and P is a input specific properties. FormInputProps interface described below:

export interface FormInputProps<V, P> {
  // input specific properties
  opts: P                                       
  // input value
  value: V                                      
  // value change handler (input specific error can be passed as a second argument)
  onChange: (value: V, error?: string) => void  
  // input error
  error?: string
  // whether input is required
  required?: boolean
}

As we can see here, each form input component is given all basic necessarry data to properly display its state and handle value updates.

Let's imagine we want to implement check box list input for our form:

import { ReactNode } from 'react'
import { FormInputProps } from 'brief-form'

import { Wrapper } from './styles'

export type CheckBoxListValue = { [key: string]: boolean }

export type CheckBoxLabels = { [key: keyof CheckBoxListValue]: ReactNode }

export type CheckBoxListOpts = {
  labels: CheckBoxLabels
  disabled?: boolean
}

export interface CheckBoxListProps extends FormInputProps<CheckBoxListValue, CheckBoxListOpts> {}

export const CheckBoxList: FC<CheckBoxListProps> = memo((props) => {
  const {
    value, // CheckBoxListValue
    onChange, // (value: CheckBoxListValue, error?: string) => void
    opts: { labels, disabled } // CheckBoxListOpts
  } = props

  return (
    <>
      ...
    </>
  )
})
Footer

P.S

Any suggestions are welcomed. Feel free to contact me by email andrey.barkanov@gmail.com.