Definition of props and behavior for validating input and other form elements

[augustocb]

Overview

When creating pages with forms, we always need to check if its data is alright.

So, in this issue we suggest a pattern to these fields, to help users by validating, formatting, and giving feedback about what they typed in the form fields.

Purpose and motivation

The main purpose is to unify the use of forms in VTEX.

In almost all cases, we must mark required fields and validate it using its format and giving some feedback to the user. We want to adopt the default char "*" to mark required fields, but it can be changed using requiredLabel described in the next topic.

In some cases, like in VTEX Checkout, we try to use only required fields in the forms, but we have some exceptions. So we want mark only these exceptions, that are Optional fields. We would do it using the optionalLabel.

For messages containing examples of how fill some input field, we understand that the best way to do it is using the helpText prop. We must write it in "Dos" section of Styleguide.

Specifications

To achieve all that needs, we suggest the creation of a new component Field that is responsible to receive some props and handle form fields to validate them.

Field props

For Input, InputButton, Dropdown, Textarea, RadioGroup

• required:bool - default: false
• requiredLabel:[" * ", " "] - default: " * "
• optionalLabel:string - default: " "

For Input, InputButton

• showValidBadge:["none", "default"] - default: "none"
• format:regex - default: ^(?!\s*$).+ (not empty)

Expected behavior

• show requiredLabel if required is true
• show optionalLabel if required is false
• If showValidBadge is true:
  • Show it while typing
  • Only remove it if the typed value doesn't match format regex
• If has format or required is true
  • Show error feedback just when not focused in
  • Clear error feedback just when started to type again
• If has format, apply format's special chars on blur. Examples:
  • BRL Postal code: 52050070 to 52050-070
  • BRL Document CPF: 052506424-90 to 052.506.424-90
  • BRL Phone number: 21988775059 to 21 98877-5059

Figma

https://www.figma.com/file/rcnqILswsqo4C4hXv3hKzo/00-Store?node-id=18387%3A79905

References

VTEX Smart Checkout fields have a similar implementation and can be used as a reference.

[emersonlaurentino]

I believe that a new component has to be created to control the form fields:

Form

Props: hideRequiredMark Hide required mark of all form fields

{
  "default": false,
  "type": "boolean"
}

showOptional Show optional message in all fields not required

{
  "default": false,
  "type": "boolean"
}

onSubmit Defines a function will be called if form data validation is successful.

{
  "default": false,
  "type": "Function(e: Event)"
}

Form.Field

Component that controls any form component.

Props: label Label text

{
  "default": "",
  "type": "string"
}

required Whether provided or not, it will be generated by the validation rule. (If marked true, it renders an asterisk)

{
  "default": false,
  "type": "boolean"
}

validateStatus The validation status. If not provided, it will be generated by validation rule

{
  "default": "",
  "type": "enum",
  "options": ["success", "warning", "error", "validating"]
}

InputMask

Component that add mask to Input Maybe use React Input Mask?

Props: mask Character to cover unfilled parts of the mask.

{
  "default": "",
  "type": "string"
}