Form Layout: new layout model

[rolfsmeds]

Description

The current FormLayout layout model is inflexible and has several issues. A new layout model based on css grid provides more flexibility, solves many of the issues, and is backward compatible with the old model.

Features

• Supports explicit grouping of fields into rows (defaulting to single column)
• Automatic breakpoints based on desired column width and available space (based on css grid and container queries)
• Side-labels doesn’t require FormItem wrapping (at least for field components)
• Field size independent of column width

Acceptance criteria

(API proposals in parenthesis)

• Automatic responsive breakpoints: can generate breakpoints automatically, based on column width (instead of each being defined separately via responsiveSteps) (auto-responsive / setAutoResponsive(boolean))
  • Plan is to use container queries for this in V25, but for V24.x we'll need a fallback implementation for Safari 15.
• vaadin-form-row element (FormRow class in Flow) for explicitly grouping fields into rows (when using single-column-default mode, see below)
• Side-labels support without explicit wrapping of fields into vaadin-form-items
  • No need to omit label from field
  • Required, invalid and focused state reflected in side label
  • Manual vaadin-form-item wrapping still supported for backward compatibility, non-field elements, and rich label support
• colspan / data-colspan works as before

Additional APIs

• Column width (column-width/setColumnWidth(String); field column width in side-labels mode)
• Label column width (label-column-width/setLabelColumnWidth(String); for side-labels mode; like current model defaults to --vaadin-form-item-label-width if defined)
• Label-spacing (for side-labels mode; existing css property --vaadin-form-item-label-spacing is sufficient)
• Maximum column count (max-columns/setMaxColumns(int); should default to something reasonable like 10)
• Toggle for expanding columns beyond defined width when there's space available (expand-columns/setExpandColumns(enum))
  • Options: always, never, mobile (on small viewports)
• Toggle for making all fields scale (grow/shrink) to fit their columns (fit-fields/setFitFields(enum))
  • Options: always, never, mobile (on small viewports)
• Side-labels mode toggle (labels-aside/setLabelPosition(LabelPosition))
  • Switches to labels-above mode if there's insufficient space for labels aside.
• Toggle for single-column (for use with explicit rows) / multi-column (old model) by default

Defaults for full backward compatibility in V24.7

• Defaults to same responsiveSteps as old version
• Defaults to expanding columns
• Still supports forcing line breaks with <br>

Nice to haves

• Form sections with titles (vaadin-form-section / FormSection)

Changes to defaults planned in V25

Enhancements

• Automatic label column width (based on label lengths)
• Automatic colspan (based on field and column width)
• Automatic column width (based on field widths)

Changes to defaults

• Automatic breakpoints instead of responsiveSteps (set responsiveSteps to revert back to old behavior)
• Single-column default mode (define rows explicitly, or set multi-column-default mode to revert back to old behavior)
• Expand-columns defaults to false (set to true to revert back to old behavior)
• Fit-fields defaults to false (set to true to revert back to old behavior)
• Global (non-instance-specific) APIs for any properties needed to revert back to old model, for easy migration of pre-V24 applications.

General criteria

• APIs reviewed

• UX/DX tests in Alpha

• Documentation:

• How to test?

• Limitations:

Security

• Security implications have been taken into account (elaborate or link to product security requirement specification if there are implications)