Fields

[andresin87]

Description

One of the most common requests a fontend has on his/her daily basis is deal with forms. We know it can seem simple until you start coding and the number of variables required to attend are exponentially increased.

The goal of that discussion is to give the full context about how do we decide to drive through our ending solution of how to deal with form fields and how do we structure that epic in many different tasks.

Spike

• Task: [Components] Text-field integration #619
• PR: feat(text-input): SPIKE #646
• Deploy: url

Pre-requisites

• Provide an easy way to manage the field tuple between input + label
• Fully compossible (compound component)
• Consistency: maintain a consistent api with the rest of the elements of the DS
  • Intent (primary/secondary/sucess/alert/danger/info/neutral/surface/)
  • Disabled/read-only aligned with other fields (radios-checkboxes-buttons-chips)
  • We decide on a previuos discussion to provide an API which uses the children prop on Checkboxes and Radios as html-labels.
  • We are currently using the prop size to manage the diferent sizes (xl, md, xs) of a component. This naming is taken for that usage so we will replace the native input size attribute name by htmlSize
• Fully accessible (a11y) solution

Definitions:

• HTML Field: we will call Field to any kind of element that the final user can interact with on a web page for inputting data.
• HTML Input : the native html input element. This includes also any kind of type attribute an input can handle.
• HTML Form: the native html form element for managing HTML Fields

Decisions

We have to consider how to tackle many different abstractions that has to be able to be made using spark-ui. For that we will identify different scenarios fully accessible (ideal situation):

Scenario 1: simple input text with its own label.

<TextField>text-label</TextField>

• simplicity
• consistant API

Scenario 2: input text labeled with helper text and semantic messages.

<FormField>
  	<TextField>text-label</TextField>
	<FormField.HelperMessage>helper text</FormField.HelperMessage>
	<FormField.ErrorMessage>error text</FormField.ErrorMessage>
</FormField>

Scenario 3: text input with its custom placed label, helper text and semantic messages.

<FormField>
	<FormField.Label>Label</FormField.Label>
	<Input />
	<FormField.HelperMessage>Helper message</FormField.HelperMessage>
	<FormField.ErrorMessage>error text</FormField.ErrorMessage>
</FormField>

Scenario 4: text input with its hidden (but declared) label

<FormField>
	<VisuallyHidden>
    	<FormField.Label>Label</FormField.Label>
  	</VisuallyHidden>
	<Input />
	<FormField.HelperMessage>Helper message</FormField.HelperMessage>
	<FormField.ErrorMessage>error text</FormField.ErrorMessage>
</FormField>

Scenario 5: text input with its label and with a left addon and a right Icon, helper text and semantic messages.

Label https:// Helper message error text ```

Scenario 7: TextArea look like a multiline TextField as a TextBlockField

<TextBlockField>textarea label</TextBlockField>

this will be equivalent to:

<Input.Group>
	<FloatingLabel>
		<TextArea />
	</FloatingLabel>
</Input.Group>

Scenario 7: verification input code (2 pin input)

<FormField>
	<Label>Label<Label>
	<Input.Group>
		<Input>
		<Input.Element>-</Input.Element>
		<Input>
	</Input.Group>
	<VisuallyHidden>
		<Input />
	</VisuallyHidden>
	<FormField.HelperMessage>Helper message</FormField.HelperMessage>
	<FormField.ErrorMessage>error text</FormField.ErrorMessage>
<FormField>

Required Components

• Input: the base html input component
• Input.Group: The base wrapper for composing multiple element inside of it and make them look like a single input all together.
• Input.Element: Every single element provided inside the input group which is not the base Input must be wrapped by that Input.Element. it will manage the spacings, colors and overflows inside of it aligned with all the Input Group.
• Input.Addon: for adding addons in any place of the InputGroup.
• TextField: the easiest way of adding an html input with its label and its transition (collapsed-expanded)
• FormField: The context provider for consuming the state (error, success, ...) of a field, easy manage the labels and the helper message.
• FormField.Label: The Label asigned to the field declared in the FromField
• FormField.HelperMessage: manages where the helperMessage is placed.
• FormField.ErrorMessage: manages when to display the error message
• FloatingLabel: a label that wraps the element given and ads the transition (collapsed/expanded) when its children get focused
• TextArea: The same as the input but with a textArea HTML Element
• TextBlockField: Equivalent to the textField but handling a textarea. (having in mind the richtextblockfield for the draft-js rich text editor)

How will we group it?

• @spark-ui/form-field
  • FormField
  • FormField.Label
  • FormField.HelperMessage
  • FormField.ErrorMessage
• @spark-ui/input
  • Input
  • InputGroup
  • InputGroup.Element
  • InputGroup.Addon
• @spark-ui/label
  • Label
  • FloatingLabel
• @spark-ui/textarea
  • TextArea
• @spark-ui/text-field
  • TextField
• @spark-ui/text-block-field
  • TextBlockField

Tasks

• Form Control Component Radix Spike #682
  • FormField
  • FormField.Label
  • FormField.HelperMessage
  • FormField.ErrorMessage
• Base Input component #760
  • Input
• Element InputGroup #762
  • InputGroup
• FloatingLabel #763
  • FloatingLabel
• Input.Element and Input.Addon parts  #764
  • Input.Element
  • Input.Addon
• Base Textarea Component #765
  • TextArea
• TextField #766
  • TextField
• TextBlockField #767
  • TextBlockField
• How to deal with forms and fields #768