@vaadin/form-layout 24.7.0-rc1 → 24.8.0-alpha2

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

@@ -3,22 +3,17 @@
  * Copyright (c) 2017 - 2025 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { isElementHidden } from '@vaadin/a11y-base/src/focus-utils.js';
-import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
-
-function isValidCSSLength(value) {
-  // Check if the value is a valid CSS length and not `inherit` or `normal`,
-  // which are also valid values for `word-spacing`, see:
-  // https://drafts.csswg.org/css-text-3/#word-spacing-property
-  return CSS.supports('word-spacing', value) && !['inherit', 'normal'].includes(value);
-}
+import { SlotStylesMixin } from '@vaadin/component-base/src/slot-styles-mixin.js';
+import { AutoResponsiveLayout } from './layouts/auto-responsive-layout.js';
+import { ResponsiveStepsLayout } from './layouts/responsive-steps-layout.js';
+import { formLayoutSlotStyles } from './vaadin-form-layout-styles.js';
 
 /**
  * @polymerMixin
- * @mixes ResizeMixin
+ * @mixes SlotStylesMixin
  */
 export const FormLayoutMixin = (superClass) =>
-  class extends ResizeMixin(superClass) {
+  class extends SlotStylesMixin(superClass) {
     static get properties() {
       return {
         /**
@@ -77,100 +72,169 @@ export const FormLayoutMixin = (superClass) =>
               { minWidth: '40em', columns: 2 },
             ];
           },
-          observer: '_responsiveStepsChanged',
+          observer: '__responsiveStepsChanged',
+          sync: true,
+        },
+
+        /**
+         * Enables the auto responsive mode in which the component automatically creates and adjusts
+         * columns based on the container's width. Columns have a fixed width defined by `columnWidth`
+         * and their number increases up to the limit set by `maxColumns`. The component dynamically
+         * adjusts the number of columns as the container size changes. When this mode is enabled,
+         * the `responsiveSteps` are ignored.
+         *
+         * By default, each field is placed on a new row. To organize fields into rows, there are
+         * two options:
+         *
+         * 1. Use `<vaadin-form-row>` to explicitly group fields into rows.
+         *
+         * 2. Enable the `autoRows` property to automatically arrange fields in available columns,
+         *    wrapping to a new row when necessary. `<br>` elements can be used to force a new row.
+         *
+         * @attr {boolean} auto-responsive
+         */
+        autoResponsive: {
+          type: Boolean,
           sync: true,
+          value: false,
+          reflectToAttribute: true,
         },
 
         /**
-         * Current number of columns in the layout
-         * @private
+         * When `autoResponsive` is enabled, defines the width of each column.
+         * The value must be defined in CSS length units, e.g., `100px` or `13em`.
+         * The default value is `13em`.
+         *
+         * @attr {string} column-width
          */
-        _columnCount: {
+        columnWidth: {
+          type: String,
+          sync: true,
+          value: '13em',
+        },
+
+        /**
+         * When `autoResponsive` is enabled, defines the maximum number of columns
+         * that the layout can create. The layout will create columns up to this
+         * limit based on the available container width. The default value is `10`.
+         *
+         * @attr {number} max-columns
+         */
+        maxColumns: {
           type: Number,
           sync: true,
+          value: 10,
         },
 
         /**
-         * Indicates that labels are on top
-         * @private
+         * When enabled with `autoResponsive`, distributes fields across columns
+         * by placing each field in the next available column and wrapping to
+         * the next row when the current row is full. `<br>` elements can be
+         * used to force a new row.
+         *
+         * @attr {boolean} auto-rows
          */
-        _labelsOnTop: {
+        autoRows: {
           type: Boolean,
           sync: true,
+          value: false,
+          reflectToAttribute: true,
+        },
+
+        /**
+         * When enabled with `autoResponsive`, `<vaadin-form-item>` prefers positioning
+         * labels beside the fields. If the layout is too narrow to fit a single column
+         * with side labels, they revert to their default position above the fields.
+         *
+         * To customize the label width and the gap between the label and the field,
+         * use the following CSS properties:
+         *
+         * - `--vaadin-form-layout-label-width`
+         * - `--vaadin-form-layout-label-spacing`
+         *
+         * @attr {boolean} labels-aside
+         */
+        labelsAside: {
+          type: Boolean,
+          sync: true,
+          value: false,
+          reflectToAttribute: true,
+        },
+
+        /**
+         * When `autoResponsive` is enabled, specifies whether the columns should expand
+         * in width to evenly fill any remaining space after the layout has created as
+         * many fixed-width (`columnWidth`) columns as possible within the `maxColumns`
+         * limit. The default value is `false`.
+         *
+         * @attr {boolean} expand-columns
+         */
+        expandColumns: {
+          type: Boolean,
+          sync: true,
+          value: false,
+          reflectToAttribute: true,
+        },
+
+        /**
+         * When `autoResponsive` is enabled, specifies whether fields should stretch
+         * to take up all available space within columns. This setting also applies
+         * to fields inside `<vaadin-form-item>` elements. The default value is `false`.
+         *
+         * @attr {boolean} expand-fields
+         */
+        expandFields: {
+          type: Boolean,
+          sync: true,
+          value: false,
+          reflectToAttribute: true,
         },
       };
     }
 
     static get observers() {
-      return ['_invokeUpdateLayout(_columnCount, _labelsOnTop)'];
+      return [
+        '__autoResponsiveLayoutPropsChanged(columnWidth, maxColumns, autoRows, labelsAside, expandColumns, expandFields)',
+        '__autoResponsiveChanged(autoResponsive)',
+      ];
     }
 
-    /** @protected */
-    connectedCallback() {
-      super.connectedCallback();
+    constructor() {
+      super();
 
-      // Set up an observer to update layout when new children are added or removed.
-      this.__childrenObserver = new MutationObserver(() => this._updateLayout());
-      this.__childrenObserver.observe(this, { childList: true });
+      /** @type {import('./layouts/abstract-layout.js').AbstractLayout} */
+      this.__currentLayout;
 
-      // Set up an observer to update layout when children's attributes change.
-      this.__childrenAttributesObserver = new MutationObserver((mutations) => {
-        if (mutations.some((mutation) => mutation.target.parentElement === this)) {
-          this._updateLayout();
-        }
-      });
-      this.__childrenAttributesObserver.observe(this, {
-        subtree: true,
-        attributes: true,
-        attributeFilter: ['colspan', 'data-colspan', 'hidden'],
-      });
+      this.__autoResponsiveLayout = new AutoResponsiveLayout(this);
+      this.__responsiveStepsLayout = new ResponsiveStepsLayout(this);
+    }
 
-      requestAnimationFrame(() => this._selectResponsiveStep());
-      requestAnimationFrame(() => this._updateLayout());
+    /** @protected */
+    connectedCallback() {
+      super.connectedCallback();
+      this.__currentLayout.connect();
     }
 
     /** @protected */
     disconnectedCallback() {
       super.disconnectedCallback();
+      this.__currentLayout.disconnect();
+    }
 
-      this.__childrenObserver.disconnect();
-      this.__childrenAttributesObserver.disconnect();
+    /** @override */
+    get slotStyles() {
+      return [`${formLayoutSlotStyles}`.replace('vaadin-form-layout', this.localName)];
     }
 
-    /** @private */
-    _naturalNumberOrOne(n) {
-      if (typeof n === 'number' && n >= 1 && n < Infinity) {
-        return Math.floor(n);
-      }
-      return 1;
+    /** @protected */
+    _updateLayout() {
+      this.__currentLayout.updateLayout();
     }
 
     /** @private */
-    _responsiveStepsChanged(responsiveSteps, oldResponsiveSteps) {
+    __responsiveStepsChanged(responsiveSteps, oldResponsiveSteps) {
       try {
-        if (!Array.isArray(responsiveSteps)) {
-          throw new Error('Invalid "responsiveSteps" type, an Array is required.');
-        }
-
-        if (responsiveSteps.length < 1) {
-          throw new Error('Invalid empty "responsiveSteps" array, at least one item is required.');
-        }
-
-        responsiveSteps.forEach((step) => {
-          if (this._naturalNumberOrOne(step.columns) !== step.columns) {
-            throw new Error(`Invalid 'columns' value of ${step.columns}, a natural number is required.`);
-          }
-
-          if (step.minWidth !== undefined && !isValidCSSLength(step.minWidth)) {
-            throw new Error(`Invalid 'minWidth' value of ${step.minWidth}, a valid CSS length required.`);
-          }
-
-          if (step.labelsPosition !== undefined && ['aside', 'top'].indexOf(step.labelsPosition) === -1) {
-            throw new Error(
-              `Invalid 'labelsPosition' value of ${step.labelsPosition}, 'aside' or 'top' string is required.`,
-            );
-          }
-        });
+        this.__responsiveStepsLayout.setProps({ responsiveSteps });
       } catch (e) {
         if (oldResponsiveSteps && oldResponsiveSteps !== responsiveSteps) {
           console.warn(`${e.message} Using previously set 'responsiveSteps' instead.`);
@@ -184,147 +248,33 @@ export const FormLayoutMixin = (superClass) =>
           ];
         }
       }
-
-      this._selectResponsiveStep();
     }
 
     /** @private */
-    _selectResponsiveStep() {
-      // Iterate through responsiveSteps and choose the step
-      let selectedStep;
-      const tmpStyleProp = 'background-position';
-      this.responsiveSteps.forEach((step) => {
-        // Convert minWidth to px units for comparison
-        this.$.layout.style.setProperty(tmpStyleProp, step.minWidth);
-        const stepMinWidthPx = parseFloat(getComputedStyle(this.$.layout).getPropertyValue(tmpStyleProp));
-
-        // Compare step min-width with the host width, select the passed step
-        if (stepMinWidthPx <= this.offsetWidth) {
-          selectedStep = step;
-        }
+    // eslint-disable-next-line @typescript-eslint/max-params
+    __autoResponsiveLayoutPropsChanged(columnWidth, maxColumns, autoRows, labelsAside, expandColumns, expandFields) {
+      this.__autoResponsiveLayout.setProps({
+        columnWidth,
+        maxColumns,
+        autoRows,
+        labelsAside,
+        expandColumns,
+        expandFields,
       });
-      this.$.layout.style.removeProperty(tmpStyleProp);
-
-      // Sometimes converting units is not possible, e.g, when element is
-      // not connected. Then the `selectedStep` stays `undefined`.
-      if (selectedStep) {
-        // Apply the chosen responsive step's properties
-        this._columnCount = selectedStep.columns;
-        this._labelsOnTop = selectedStep.labelsPosition === 'top';
-      }
     }
 
     /** @private */
-    _invokeUpdateLayout() {
-      this._updateLayout();
-    }
-
-    /**
-     * Update the layout.
-     * @protected
-     */
-    _updateLayout() {
-      // Do not update layout when invisible
-      if (isElementHidden(this)) {
-        return;
+    __autoResponsiveChanged(autoResponsive) {
+      if (this.__currentLayout) {
+        this.__currentLayout.disconnect();
       }
 
-      /*
-        The item width formula:
-
-            itemWidth = colspan / columnCount * 100% - columnSpacing
-
-        We have to subtract columnSpacing, because the column spacing space is taken
-        by item margins of 1/2 * spacing on both sides
-      */
-
-      const style = getComputedStyle(this);
-      const columnSpacing = style.getPropertyValue('--vaadin-form-layout-column-spacing');
-
-      const direction = style.direction;
-      const marginStartProp = `margin-${direction === 'ltr' ? 'left' : 'right'}`;
-      const marginEndProp = `margin-${direction === 'ltr' ? 'right' : 'left'}`;
-
-      const containerWidth = this.offsetWidth;
-
-      let col = 0;
-      Array.from(this.children)
-        .filter((child) => child.localName === 'br' || getComputedStyle(child).display !== 'none')
-        .forEach((child, index, children) => {
-          if (child.localName === 'br') {
-            // Reset column count on line break
-            col = 0;
-            return;
-          }
-
-          const attrColspan = child.getAttribute('colspan') || child.getAttribute('data-colspan');
-          let colspan;
-          colspan = this._naturalNumberOrOne(parseFloat(attrColspan));
-
-          // Never span further than the number of columns
-          colspan = Math.min(colspan, this._columnCount);
-
-          const childRatio = colspan / this._columnCount;
-          child.style.width = `calc(${childRatio * 100}% - ${1 - childRatio} * ${columnSpacing})`;
-
-          if (col + colspan > this._columnCount) {
-            // Too big to fit on this row, let's wrap it
-            col = 0;
-          }
-
-          // At the start edge
-          if (col === 0) {
-            child.style.setProperty(marginStartProp, '0px');
-          } else {
-            child.style.removeProperty(marginStartProp);
-          }
-
-          const nextIndex = index + 1;
-          const nextLineBreak = nextIndex < children.length && children[nextIndex].localName === 'br';
-
-          // At the end edge
-          if (col + colspan === this._columnCount) {
-            child.style.setProperty(marginEndProp, '0px');
-          } else if (nextLineBreak) {
-            const colspanRatio = (this._columnCount - col - colspan) / this._columnCount;
-            child.style.setProperty(
-              marginEndProp,
-              `calc(${colspanRatio * containerWidth}px + ${colspanRatio} * ${columnSpacing})`,
-            );
-          } else {
-            child.style.removeProperty(marginEndProp);
-          }
-
-          // Move the column counter
-          col = (col + colspan) % this._columnCount;
-
-          if (child.localName === 'vaadin-form-item') {
-            if (this._labelsOnTop) {
-              if (child.getAttribute('label-position') !== 'top') {
-                child.__useLayoutLabelPosition = true;
-                child.setAttribute('label-position', 'top');
-              }
-            } else if (child.__useLayoutLabelPosition) {
-              delete child.__useLayoutLabelPosition;
-              child.removeAttribute('label-position');
-            }
-          }
-        });
-    }
-
-    /**
-     * @protected
-     * @override
-     */
-    _onResize(contentRect) {
-      if (contentRect.width === 0 && contentRect.height === 0) {
-        this.$.layout.style.opacity = '0';
-        return;
+      if (autoResponsive) {
+        this.__currentLayout = this.__autoResponsiveLayout;
+      } else {
+        this.__currentLayout = this.__responsiveStepsLayout;
       }
 
-      this._selectResponsiveStep();
-      this._updateLayout();
-
-      this.$.layout.style.opacity = '';
+      this.__currentLayout.connect();
     }
   };

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,167 @@ export const formLayoutStyles = css`
   #layout ::slotted(br) {
     display: none;
   }
+
+  :host([auto-responsive]) {
+    --_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 +211,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;