@vaadin/form-layout 24.7.2 → 24.8.0-alpha10

package/src/vaadin-form-layout-styles.js

@@ -22,7 +22,7 @@ export const formLayoutStyles = css`
     display: none !important;
   }
 
-  #layout {
+  :host(:not([auto-responsive])) #layout {
     display: flex;
 
     align-items: baseline; /* default \`stretch\` is not appropriate */
@@ -30,7 +30,7 @@ export const formLayoutStyles = css`
     flex-wrap: wrap; /* the items should wrap */
   }
 
-  #layout ::slotted(*) {
+  :host(:not([auto-responsive])) #layout ::slotted(*) {
     /* Items should neither grow nor shrink. */
     flex-grow: 0;
     flex-shrink: 0;
@@ -43,19 +43,168 @@ export const formLayoutStyles = css`
   #layout ::slotted(br) {
     display: none;
   }
+
+  :host([auto-responsive]) {
+    --_column-width: var(--vaadin-field-default-width, 12em);
+    --_column-width-labels-above: var(--_column-width);
+    --_column-width-labels-aside: calc(
+      var(--_column-width) + var(--vaadin-form-layout-label-width) + var(--vaadin-form-layout-label-spacing)
+    );
+
+    display: flex;
+    min-width: var(--_column-width-labels-above);
+  }
+
+  :host([auto-responsive]) #layout {
+    /* By default, labels should be displayed above the fields */
+    --_form-item-labels-above: initial; /* true */
+    --_form-item-labels-aside: ' '; /* false */
+
+    /* CSS grid related properties */
+    --_grid-column-gap: var(--vaadin-form-layout-column-spacing);
+    --_grid-column-width: var(--_column-width-labels-above);
+    --_grid-column-max-total-gap: calc((var(--_max-columns) - 1) * var(--_grid-column-gap));
+    --_grid-column-max-total-width: calc(var(--_max-columns) * var(--_column-width-labels-above));
+    --_grid-repeat: var(--_grid-column-width);
+
+    display: grid;
+    grid-template-columns: repeat(auto-fill, var(--_grid-repeat));
+
+    /*
+      Auto-columns can be created when an item's colspan exceeds the rendered column count.
+      By setting auto-columns to 0, we exclude these columns from --_grid-rendered-column-count,
+      which is then used to cap the colspan.
+    */
+    grid-auto-columns: 0;
+
+    justify-items: start;
+    gap: var(--vaadin-form-layout-row-spacing) var(--_grid-column-gap);
+
+    /*
+      To prevent the layout from exceeding the column limit defined by --_max-columns,
+      its width needs to be constrained:
+
+      1. "width" is used instead of "max-width" because, together with the default "flex: 0 1 auto",
+      it allows the layout to shrink to its minimum width inside <vaadin-horizontal-layout>, which
+      wouldn't work otherwise.
+
+      2. "width" is used instead of "flex-basis" to make the layout expand to the maximum
+      number of columns inside <vaadin-overlay>, which creates a new stacking context
+      without a predefined width.
+    */
+    width: calc(var(--_grid-column-max-total-width) + var(--_grid-column-max-total-gap));
+
+    /*
+      Firefox requires min-width on both :host and #layout to allow the layout
+      to shrink below the value specified in the CSS width property above.
+    */
+    min-width: inherit;
+  }
+
+  :host([auto-responsive]) #layout::before {
+    background-position-y: var(--_column-width-labels-aside);
+  }
+
+  :host([auto-responsive]) #layout ::slotted(*) {
+    /* Make form items inherit label position from the layout */
+    --_form-item-labels-above: inherit;
+    --_form-item-labels-aside: inherit;
+
+    /* By default, place each child on a new row */
+    grid-column: 1 / span min(var(--_grid-colspan, 1), var(--_grid-rendered-column-count));
+  }
+
+  :host([auto-responsive][auto-rows]) #layout ::slotted(*) {
+    grid-column-start: var(--_grid-colstart, auto);
+  }
+
+  :host([auto-responsive][labels-aside]) #layout {
+    --_grid-column-max-total-width: calc(var(--_max-columns) * var(--_column-width-labels-aside));
+  }
+
+  :host([auto-responsive][labels-aside]) #layout[fits-labels-aside] {
+    --_form-item-labels-above: ' '; /* false */
+    --_form-item-labels-aside: initial; /* true */
+    --_grid-column-width: var(--_column-width-labels-aside);
+  }
+
+  :host([auto-responsive][expand-columns]) #layout {
+    /*
+      The "min" value in minmax ensures that once "maxColumns" is reached, the grid stops adding
+      new columns and instead expands the existing ones evenly to fill the available space.
+
+      The "max" value in minmax allows CSS grid columns to grow and evenly distribute any space
+      that remains when there isn't room for an additional column and "maxColumns" hasn't been
+      reached yet.
+    */
+    --_grid-repeat: minmax(
+      max(var(--_grid-column-width), calc((100% - var(--_grid-column-max-total-gap)) / var(--_max-columns))),
+      1fr
+    );
+
+    /* Allow the layout to take up full available width of the parent element. */
+    flex-grow: 1;
+  }
+`;
+
+export const formLayoutSlotStyles = css`
+  /* Using :where to ensure user styles always take precedence */
+  :where(
+      vaadin-form-layout[auto-responsive] > *,
+      vaadin-form-layout[auto-responsive] vaadin-form-row > *,
+      vaadin-form-layout[auto-responsive] vaadin-form-item > *
+    ) {
+    box-sizing: border-box;
+    max-width: 100%;
+  }
+
+  :where(
+      vaadin-form-layout[auto-responsive][expand-fields] > *,
+      vaadin-form-layout[auto-responsive][expand-fields] vaadin-form-row > *,
+      vaadin-form-layout[auto-responsive][expand-fields] vaadin-form-item > *
+    ) {
+    min-width: 100%;
+  }
+`;
+
+export const formRowStyles = css`
+  :host {
+    display: contents;
+  }
+
+  :host([hidden]) {
+    display: none !important;
+  }
+
+  ::slotted(*) {
+    /* Make form items inherit label position from the layout */
+    --_form-item-labels-above: inherit;
+    --_form-item-labels-aside: inherit;
+
+    grid-column: auto / span min(var(--_grid-colspan, 1), var(--_grid-rendered-column-count));
+  }
+
+  ::slotted(:first-child) {
+    grid-column-start: 1;
+  }
 `;
 
 export const formItemStyles = css`
   :host {
+    /* By default, when auto-responsive mode is disabled, labels should be displayed beside the fields. */
+    --_form-item-labels-above: ' '; /* false */
+    --_form-item-labels-aside: initial; /* true */
+
     display: inline-flex;
-    flex-direction: row;
-    align-items: baseline;
+    align-items: var(--_form-item-labels-aside, baseline);
+    flex-flow: var(--_form-item-labels-above, column) nowrap;
+    justify-self: stretch;
     margin: calc(0.5 * var(--vaadin-form-item-row-spacing, var(--vaadin-form-layout-row-spacing, 1em))) 0;
   }
 
   :host([label-position='top']) {
-    flex-direction: column;
-    align-items: stretch;
+    --_form-item-labels-above: initial; /* true */
+    --_form-item-labels-aside: ' '; /* false */
   }
 
   :host([hidden]) {
@@ -63,14 +212,13 @@ export const formItemStyles = css`
   }
 
   #label {
-    width: var(--vaadin-form-item-label-width, var(--vaadin-form-layout-label-width, 8em));
+    width: var(
+      --_form-item-labels-aside,
+      var(--vaadin-form-item-label-width, var(--vaadin-form-layout-label-width, 8em))
+    );
     flex: 0 0 auto;
   }
 
-  :host([label-position='top']) #label {
-    width: auto;
-  }
-
   #spacing {
     width: var(--vaadin-form-item-label-spacing, var(--vaadin-form-layout-label-spacing, 1em));
     flex: 0 0 auto;

package/src/vaadin-form-layout.d.ts

@@ -90,6 +90,101 @@ export * from './vaadin-form-layout-mixin.js';
  * </vaadin-form-layout>
  * ```
  *
+ * ### Auto Responsive Mode
+ *
+ * To avoid manually dealing with responsive breakpoints, Form Layout provides an auto-responsive mode
+ * that automatically creates and adjusts fixed-width columns based on the container's available space.
+ *
+ * The [`columnWidth`](#/elements/vaadin-form-layout#property-columnWidth) and
+ * [`maxColumns`](#/elements/vaadin-form-layout#property-maxColumns) properties define the width of
+ * each column and the maximum number of columns that the component can create. By default, the component
+ * creates up to 10 columns, each with a width of `12em` or the value of the `--vaadin-field-default-width`
+ * CSS custom property, if defined.
+ *
+ * The auto-responsive mode is disabled by default. To enable it for an individual instance, set the
+ * `auto-responsive` attribute:
+ *
+ * ```html
+ * <vaadin-form-layout auto-responsive>
+ *   <vaadin-text-field label="First Name"></vaadin-text-field>
+ *   <vaadin-text-field label="Last Name"></vaadin-text-field>
+ *   <vaadin-text-area label="Address" colspan="2"></vaadin-text-area>
+ * </vaadin-form-layout>
+ * ```
+ *
+ * You can also enable it for all instances by enabling the following feature flag
+ * before `<vaadin-form-layout>` elements are added to the DOM:
+ *
+ * ```js
+ * window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true;
+ * ```
+ *
+ * #### Organizing Fields into Rows
+ *
+ * By default, each field is placed on a new row. To organize fields into rows, you can either:
+ *
+ * 1. Manually wrap fields into [`<vaadin-form-row>`](#/elements/vaadin-form-row) elements.
+ *
+ * 2. Enable the [`autoRows`](#/elements/vaadin-form-layout#property-autoRows) property to
+ *    let Form Layout automatically arrange fields in available columns, wrapping to a new
+ *    row when necessary. `<br>` elements can be used to force a new row.
+ *
+ * Here is an example of using `<vaadin-form-row>`:
+ *
+ * ```html
+ * <vaadin-form-layout auto-responsive>
+ *   <vaadin-form-row>
+ *     <vaadin-text-field label="First Name"></vaadin-text-field>
+ *     <vaadin-text-field label="Last Name"></vaadin-text-field>
+ *   </vaadin-form-row>
+ *   <vaadin-form-row>
+ *     <vaadin-text-area label="Address" colspan="2"></vaadin-text-area>
+ *   </vaadin-form-row>
+ * </vaadin-form-layout>
+ * ```
+ *
+ * #### Expanding Columns and Fields
+ *
+ * You can configure Form Layout to expand columns to evenly fill any remaining space after
+ * all fixed-width columns have been created.
+ * To enable this, set the [`expandColumns`](#/elements/vaadin-form-layout#property-expandColumns)
+ * property to `true`.
+ *
+ * Also, Form Layout can stretch fields to make them take up all available space within columns.
+ * To enable this, set the [`expandFields`](#/elements/vaadin-form-layout#property-expandFields)
+ * property to `true`.
+ *
+ * #### Customizing Label Position
+ *
+ * By default, Form Layout displays labels above the fields. To position labels beside fields, you
+ * need to wrap each field in a `<vaadin-form-item>` element and define its labels on the wrapper.
+ * Then, you can enable the [`labelsAside`](#/elements/vaadin-form-layout#property-labelsAside)
+ * property:
+ *
+ * ```html
+ * <vaadin-form-layout auto-responsive labels-aside>
+ *   <vaadin-form-row>
+ *     <vaadin-form-item>
+ *       <label slot="label">First Name</label>
+ *       <vaadin-text-field></vaadin-text-field>
+ *    </vaadin-form-item>
+ *    <vaadin-form-item>
+ *      <label slot="label">Last Name</label>
+ *       <vaadin-text-field></vaadin-text-field>
+ *     </vaadin-form-item>
+ *   </vaadin-form-row>
+ *   <vaadin-form-row>
+ *     <vaadin-form-item colspan="2">
+ *       <label slot="label">Address</label>
+ *       <vaadin-text-area></vaadin-text-area>
+ *     </vaadin-form-item>
+ *   </vaadin-form-row>
+ * </vaadin-form-layout>
+ * ```
+ *
+ * With this, FormLayout will display labels beside fields, falling back to
+ * the default position above the fields only when there isn't enough space.
+ *
  * ### CSS Properties Reference
  *
  * The following custom CSS properties are available on the `<vaadin-form-layout>`
@@ -99,6 +194,8 @@ export * from './vaadin-form-layout-mixin.js';
  * ---|---|---
  * `--vaadin-form-layout-column-spacing` | Length of the spacing between columns | `2em`
  * `--vaadin-form-layout-row-spacing` | Length of the spacing between rows | `1em`
+ * `--vaadin-form-layout-label-width` | Width of the label when labels are displayed aside | `8em`
+ * `--vaadin-form-layout-label-spacing` | Length of the spacing between the label and the input when labels are displayed aside | `1em`
  */
 declare class FormLayout extends FormLayoutMixin(ElementMixin(ThemableMixin(HTMLElement))) {}
 

package/src/vaadin-form-layout.js

@@ -93,6 +93,101 @@ registerStyles('vaadin-form-layout', formLayoutStyles, { moduleId: 'vaadin-form-
  * </vaadin-form-layout>
  * ```
  *
+ * ### Auto Responsive Mode
+ *
+ * To avoid manually dealing with responsive breakpoints, Form Layout provides an auto-responsive mode
+ * that automatically creates and adjusts fixed-width columns based on the container's available space.
+ *
+ * The [`columnWidth`](#/elements/vaadin-form-layout#property-columnWidth) and
+ * [`maxColumns`](#/elements/vaadin-form-layout#property-maxColumns) properties define the width of
+ * each column and the maximum number of columns that the component can create. By default, the component
+ * creates up to 10 columns, each with a width of `12em` or the value of the `--vaadin-field-default-width`
+ * CSS custom property, if defined.
+ *
+ * The auto-responsive mode is disabled by default. To enable it for an individual instance, set the
+ * `auto-responsive` attribute:
+ *
+ * ```html
+ * <vaadin-form-layout auto-responsive>
+ *   <vaadin-text-field label="First Name"></vaadin-text-field>
+ *   <vaadin-text-field label="Last Name"></vaadin-text-field>
+ *   <vaadin-text-area label="Address" colspan="2"></vaadin-text-area>
+ * </vaadin-form-layout>
+ * ```
+ *
+ * You can also enable it for all instances by enabling the following feature flag
+ * before `<vaadin-form-layout>` elements are added to the DOM:
+ *
+ * ```js
+ * window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true;
+ * ```
+ *
+ * #### Organizing Fields into Rows
+ *
+ * By default, each field is placed on a new row. To organize fields into rows, you can either:
+ *
+ * 1. Manually wrap fields into [`<vaadin-form-row>`](#/elements/vaadin-form-row) elements.
+ *
+ * 2. Enable the [`autoRows`](#/elements/vaadin-form-layout#property-autoRows) property to
+ *    let Form Layout automatically arrange fields in available columns, wrapping to a new
+ *    row when necessary. `<br>` elements can be used to force a new row.
+ *
+ * Here is an example of using `<vaadin-form-row>`:
+ *
+ * ```html
+ * <vaadin-form-layout auto-responsive>
+ *   <vaadin-form-row>
+ *     <vaadin-text-field label="First Name"></vaadin-text-field>
+ *     <vaadin-text-field label="Last Name"></vaadin-text-field>
+ *   </vaadin-form-row>
+ *   <vaadin-form-row>
+ *     <vaadin-text-area label="Address" colspan="2"></vaadin-text-area>
+ *   </vaadin-form-row>
+ * </vaadin-form-layout>
+ * ```
+ *
+ * #### Expanding Columns and Fields
+ *
+ * You can configure Form Layout to expand columns to evenly fill any remaining space after
+ * all fixed-width columns have been created.
+ * To enable this, set the [`expandColumns`](#/elements/vaadin-form-layout#property-expandColumns)
+ * property to `true`.
+ *
+ * Also, Form Layout can stretch fields to make them take up all available space within columns.
+ * To enable this, set the [`expandFields`](#/elements/vaadin-form-layout#property-expandFields)
+ * property to `true`.
+ *
+ * #### Customizing Label Position
+ *
+ * By default, Form Layout displays labels above the fields. To position labels beside fields, you
+ * need to wrap each field in a `<vaadin-form-item>` element and define its labels on the wrapper.
+ * Then, you can enable the [`labelsAside`](#/elements/vaadin-form-layout#property-labelsAside)
+ * property:
+ *
+ * ```html
+ * <vaadin-form-layout auto-responsive labels-aside>
+ *   <vaadin-form-row>
+ *     <vaadin-form-item>
+ *       <label slot="label">First Name</label>
+ *       <vaadin-text-field></vaadin-text-field>
+ *    </vaadin-form-item>
+ *    <vaadin-form-item>
+ *      <label slot="label">Last Name</label>
+ *       <vaadin-text-field></vaadin-text-field>
+ *     </vaadin-form-item>
+ *   </vaadin-form-row>
+ *   <vaadin-form-row>
+ *     <vaadin-form-item colspan="2">
+ *       <label slot="label">Address</label>
+ *       <vaadin-text-area></vaadin-text-area>
+ *     </vaadin-form-item>
+ *   </vaadin-form-row>
+ * </vaadin-form-layout>
+ * ```
+ *
+ * With this, FormLayout will display labels beside fields, falling back to
+ * the default position above the fields only when there isn't enough space.
+ *
  * ### CSS Properties Reference
  *
  * The following custom CSS properties are available on the `<vaadin-form-layout>`

package/src/vaadin-form-row.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+/**
+ * `<vaadin-form-row>` is a web component for arranging fields into rows
+ * inside a `<vaadin-form-layout>` that is set to autoResponsive mode.
+ *
+ * Each `<vaadin-form-row>` always starts on a new row. Fields that exceed
+ * the available columns wrap to a new row, which then remains reserved
+ * exclusively for the fields of that `<vaadin-form-row>` element.
+ */
+declare class FormRow extends ThemableMixin(HTMLElement) {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vaadin-form-row': FormRow;
+  }
+}
+
+export { FormRow };

package/src/vaadin-form-row.js

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { html, PolymerElement } from '@polymer/polymer/polymer-element.js';
+import { defineCustomElement } from '@vaadin/component-base/src/define.js';
+import { registerStyles, ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { formRowStyles } from './vaadin-form-layout-styles.js';
+
+registerStyles('vaadin-form-row', formRowStyles, { moduleId: 'vaadin-form-row-styles' });
+
+/**
+ * `<vaadin-form-row>` is a web component for arranging fields into rows
+ * inside a `<vaadin-form-layout>` that is set to autoResponsive mode.
+ *
+ * Each `<vaadin-form-row>` always starts on a new row. Fields that exceed
+ * the available columns wrap to a new row, which then remains reserved
+ * exclusively for the fields of that `<vaadin-form-row>` element.
+ *
+ * @customElement
+ * @extends HTMLElement
+ * @mixes ThemableMixin
+ */
+class FormRow extends ThemableMixin(PolymerElement) {
+  static get is() {
+    return 'vaadin-form-row';
+  }
+
+  static get template() {
+    return html`<slot></slot>`;
+  }
+}
+
+defineCustomElement(FormRow);
+
+export { FormRow };

package/src/vaadin-lit-form-row.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+export * from './vaadin-form-row.js';

package/src/vaadin-lit-form-row.js

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { html, LitElement } from 'lit';
+import { defineCustomElement } from '@vaadin/component-base/src/define.js';
+import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { formRowStyles } from './vaadin-form-layout-styles.js';
+
+/**
+ * LitElement based version of `<vaadin-form-row>` web component.
+ *
+ * ## Disclaimer
+ *
+ * This component is an experiment and not yet a part of Vaadin platform.
+ * There is no ETA regarding specific Vaadin version where it'll land.
+ * Feel free to try this code in your apps as per Apache 2.0 license.
+ */
+class FormRow extends ThemableMixin(PolylitMixin(LitElement)) {
+  static get is() {
+    return 'vaadin-form-row';
+  }
+
+  static get styles() {
+    return formRowStyles;
+  }
+
+  /** @protected */
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+defineCustomElement(FormRow);
+
+export { FormRow };

package/theme/lumo/vaadin-form-row.d.ts

@@ -0,0 +1 @@
+import '../../src/vaadin-form-row.js';

package/theme/lumo/vaadin-form-row.js

@@ -0,0 +1 @@
+import '../../src/vaadin-form-row.js';

package/theme/lumo/vaadin-lit-form-row.d.ts

@@ -0,0 +1 @@
+import '../../src/vaadin-lit-form-row.js';

package/theme/lumo/vaadin-lit-form-row.js

@@ -0,0 +1 @@
+import '../../src/vaadin-lit-form-row.js';

package/theme/material/vaadin-form-row.d.ts

@@ -0,0 +1 @@
+import '../../src/vaadin-form-row.js';

package/theme/material/vaadin-form-row.js

@@ -0,0 +1 @@
+import '../../src/vaadin-form-row.js';

package/theme/material/vaadin-lit-form-row.d.ts

@@ -0,0 +1 @@
+import '../../src/vaadin-lit-form-row.js';

package/theme/material/vaadin-lit-form-row.js

@@ -0,0 +1 @@
+import '../../src/vaadin-lit-form-row.js';

package/vaadin-form-row.d.ts

@@ -0,0 +1 @@
+export * from './src/vaadin-form-row.js';

package/vaadin-form-row.js

@@ -0,0 +1,2 @@
+import './theme/lumo/vaadin-form-row.js';
+export * from './src/vaadin-form-row.js';

package/vaadin-lit-form-row.d.ts

@@ -0,0 +1 @@
+export * from './vaadin-form-row.js';

package/vaadin-lit-form-row.js

@@ -0,0 +1,2 @@
+import './theme/lumo/vaadin-lit-form-row.js';
+export * from './src/vaadin-lit-form-row.js';