Issues to cover

Validations
- Invalid values
- Blank mandatory fields
Form-level elements
- Status tags
- Messages
Action buttons
- Distances between buttons (if more than 2)
Guidance
- Form instructions
- Field help
- Ask Femi about web SDK form guidance
Autosave

Description

A form is a collection of input fields, allowing users to enter data that is then sent for further processing.
Forms may appear in workspaces, dialog popups, popovers, wizards, filter panes, details panes and cards.

Types

Type	Description	Example
Configuration forms	Allowing users to update predefined configurations.
Create / edit forms	Allowing users to create and edit objects. By default, most of the fields are blank.

Usage & Behavior

Structure

A form consists of two areas: the input area and the action area.
The input area may contain any set of input fields, including text fields, dropdown menus, checkboxes, radio buttons etc.
A collection of related fields can be grouped into a section. For example, fields like Email and Phone can be found under a section called Contact Information.
The action area usually consists of two buttons: Save (or Create, or Update) and Cancel.
The action area will always be visible. In case the form takes up the entire workspace, the action area will appear at the top of the page.
In any other case, it will appear below the form:
- In dialog popups, popovers, wizards, filter panes, details panes and cards, the action are will appear at the bottom of the container.
- In workspaces:
  - If the form exceeds the height of its container, the action area will stick to the bottom of the container, allowing users to scroll the form above it.
  - If the form does not exceed the height of its container, the action area will appear directly below the last field of the form.

Add examples

Placement and Positioning

Do we need anything here?

Fields

Field labels will appear on top of the input field (e.g., a text field or a set of radio buttons).
On mandatory fields, a mandatory indicator ( ) will be shown next to the label.
Where relevant, a help icons will appear next to the label.
In some cases, two or more fields will be dependent. In this case, selecting a value for the dependent fields will not be possible until a value exists in the main field.

States

Forms can have 3 states:
- Idle - this is the default for creation forms. Exiting the form without changing anything will not add that entity.
- Dirty state - a form switches to this state after making changes to the idle form.
- Saved - after clicking the Save button.
When first opening a configuration form it is defined as saved. Updating any of the fields, switches it to dirty state.

Interaction

Forms has no intrinsic interactions. For component-specific interactions see the documentation of that component.

Validations and errors

There are two types of validations related to forms: field validation and form validation.

Field Validation

This category includes all validations that are related to specific inputs, including text fields, text areas, sets of checkboxes, date and time pickers, etc.
The most common input-level errors are:
- Invalid data, including invalid characters, invalid format and out-of-range values.
- Missing mandatory, where a required field was left blank.
Field validations for invalid characters or invalid format occurs while typing (“onkeydown”).
Field validations for out of range data or missing mandatory occurs when a field looses focus (“onblur”).
When invalid data or missing mandatory field was detected, the field changes its status to error.
In some cases, the entered value is valid, but may call for a special attention (for example: a very large value). In this case, the field will change its status to warning, but will not prevent the form from being submitted.
For more information, please refer to LUX Field Validation page.

Form Validation

A form cannot be saved / submitted if one or more of its fields are in error state.
Here is a typical saving flow:
- When first entering a form, the Save button is disabled.
- On updating a field, the Save button becomes enabled.
- In case of a field error the Save button becomes disabled. An additional form-level indication may appear. Only after the error was resolved, the Save button is enabled again.
- After clicking the Save button:
  - it becomes disabled again,
  - a toast message may appear, indicating that the form was saved.
This flow is also relevant when the form is in a dialog popup. In this case, the cancel button is always enabled.

Saving “dirty data” in local storage

In case a single Save button applies to multiple areas (tabs, master items in a master-detail layout, etc.), updated values will be saved in a local storage even before clicking the Save button.
In this case, if the user updated a value in the first area, navigated to another area and went back to the first area, all updated values will remain intact.

Edge case: navigating to another area of the form while some fields has errors

In case the user tries to navigate to another area of the form, while the current area has errors, a message popup will appear, allowing him to either continue, while loosing all the updated data, or cancel.

Edge case: exiting an updated form

In case the user tries to navigate away from a form after updating one or more fields, a message popup will appear, allowing her to either save and exit, exit without saving, or cancel.

Best practices

Use when:

Values have a distinct order.
There is a default value.
There are at least three possible values.

Don’t use:

When?

General

In case of large number of fields, group related fields together, providing a clear title to each group.
Make sure that label texts are not selectable.
Make sure there is a natural tab order between fields.

Accessibility compliance

Unless otherwise specified, see our general compliance information in Fundamentals - Accessibility

text highlight when using a keyboard + using arrows when in edit mode (left, up or home to set the insertion point at the beginning; right, down or end to set it at the end).

Design

Zeplin link	Screen thumbnail
<<Short Zeplin link. You Use this >>	<<Screen with 200 width>>

Code

<<a box containing the code - discuss with Femi>>