@vai-software/use-ful-form

1 - Introduction

This hook is useful for managing forms: input validation, formatting and saving values. It works with any input but it is recommended to use the <InputField /> present in our UIKit.

The input component should receive the required props using the getInputProps function returned by the hook. Those props are:

• value: the current input value
• setValue(value): set the input value, to be used in onInput
• isValid: boolean, true if valid, false if there is an error, null if error should not be shown
• errorDetails: error informations returned by the validator. Usually a string but may be an object, it depends on the validator output (see below)
• setShowErrors(): to be called to manually trigger error show (usually in onBlur)

When the value changes, the following actions will be performed by the hook:

1. Pass the new value to the formatter and saves the output
2. For every input, if the input has the required option, executes a function based on the input nature, for example email and username are required to be not empty while checkbox has to be true. If it does not pass the check, a generic error is set, otherwise continues.
3. Validation is performed for every input: if it is set a validator for the input that function is executed, otherwise one is chosen based on the nature, if available

Errors are not always shown: the input has to signal it, for example on blur.

2 - How to use it

To install execute:

npm install @vai-software/use-ful-form

Then you can import useForm with import useForm from "@vai-software/use-ful-form"

The hook requires an object as argument with the following keys:

| Parameter | Type | Description | | --------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | inputs | Input[] | An object where the keys are the ids of the inputs and the value follows the format described in the section below. | | onSubmit | ({data: any, apiBody: any}) => void (optional) | A function called when calling the .submit() function or when the user presses the enter key in an input. |

2.1 - Input parameters

The parameter is a dictionary where the keys are the identifiers of the fields and the value is a dictionary with the following parameters:

| Parameter | Type | Default | Description | | --------- | -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | value | string (optional) | | Initial value. Default depends on the input nature, see below. | | nature | string (optional) | | email, username, password, confirmPassword, or checkbox. More details below. | | apiName | string (optional) | | The name of the input returned by the getApiBody function, by default is the input key. | | required | boolean (optional) | false | If the input is required. | | validator | Validator (optional) | | The validation function, see the next section to know how it works and the one about input natures to learn about the default ones. More information below. | | formatter | Formatter (optional) | | A function to format the input whenever its value changes. More information below. | | sendToApi | boolean (optional) | true | If the input value should be returned bu the getApiBody function. |

2.2 - Returned values

| Parameter | Type | Description | | -------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | values | { [key: string]: InputValue } | A dictionary containing the values of all the inputs. | | setInputValue | (key: string, value: InputValue, showErrors?: boolean) => void | Function used to set the value of a specific input. The optional showErrors parameter allows to show the error message if there is any. | | errors | { [key: string]: ValidationError } | A dictionary containing the errors of all the inputs. The error is a list where the first element is a boolean that stands for valid yes/no and the second value is the error message (or null). | | setInputError | (key: string, error: string) => void | Function that can be used to force an error message for an input. | | getInputProps | (key: string, options?: GetInputPropsOptions) => InputProps | Function that returns the necessary functions and values of an input to get and update its value and get the error. | | resetInput | (input: string) => void | Function that resets the input's value to its initial state. | | isValid | boolean | True if the form passed all the validations, False otherwise. | | validate | () => boolean | Function that shows all the errors and returns true if the form passed all the validations or false otherwise. | | reset | () => void | Function that resets the form to its initial state. | | submit | () => void | Function that shows all the errors and only if the form passed all the validation checks calls the onSubmit function. | | getApiBody | () => any | Returns the body that sould be sent in the API call. The output is a JSON with the format { apiName: value } | | fetchApiErrors | (receivedErrors: any) => void | Function that gets a JSON with api name as key and error details and adds the errors to the form. | | fetchApiValues | (data, {include, exclude}) => void | Function that gets data as an object with apiName: value format to set in the form the values returned by an API. include and exclude are two optional string lists that should contain apiNames and allow to set only specific fields or exclude some from the data | | pushApiError | (apiName: string, errorDetails: string | Array) => void | The same as setInputError but using the apiName. | | pushApiValue | (apiName: string, value: InputValue) => void | The same as setInputValue but using the apiName. |

2.3 - Input props

| Parameter | Type | Description | | ------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | value | InputValue | The value of the input. | | setValue | (value: InputValue, showErrors?: boolean) => void | Function used to set the value of the input. The optional showErrors parameter allows to show the error message if there is any. | | isValid | boolean | False if there is an error and it has to be shown, True otherwise. | | errorDetails | any | The error message if there is a problem and it has to be shown, otherwise null. | | setShowErrors | () => void | Function that when called signals to the form that from then on, the error message should be shown. | | resetInput | () => void | Function that resets the input's value to its initial state. | | submitForm | () => void | The same as calling submit for the form. | | onKeyDown | (e: React.KeyboardEvent) => void (optional) | Returned only if the handleKeyDown option is true in getInputProps. |

3 - Validation and formatting

3.1 - Validation function

The validation function receives two arguments:

• value which is the value of the input being validated
• values which is an object containing the values of all inputs

The output should be a list with two items inside:

• The first one is a validator which will set isValid for the input
• The secount one will set the error details. Is suggested to insert a string but any data type will work

Some prebuilt validators are available and can be imported from @vai-software/use-ful-form:

• validateConfirmPassword: checks that the value is the same as the one of the input named "password".
• validateEmail: validates the email format using a regex.
• validatePassword: this validator is different because does not return a string but an object with message and security ("none" | "low" | "medium" | "high" | "strong").

3.2 - Formatter

A formatter is a function that receives the original value as input every time the input changes and should return a formatted value.

Some prebuilt formatters are available and can be imported from @vai-software/use-ful-form:

• formatEmail: transform the string to lowercase and remove the spaces.
• formatLowerCase: transform the string to lowercase.
• formatUsername: : transform the string to lowercase and allow only letters, numbers, dots and underscores.

4 - Available input natures

| nature | default value | default validator | default formatter | default validator when required | | --------------- | ------------- | ------------------------- | ----------------- | ------------------------------- | | email | "" | validateEmail | formatEmail | validateRequiredString | | username | "" | | formatUsername | validateRequiredString | | password | "" | validatePassword | | validateRequiredString | | confirmPassword | "" | validateConfirmPassword | | validateRequiredString | | checkbox | false | | | validateRequiredCheckbox |