@vaadin/form-layout 24.7.2 → 24.8.0-alpha10

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

@@ -4,7 +4,7 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import type { Constructor } from '@open-wc/dedupe-mixin';
-import type { ResizeMixinClass } from '@vaadin/component-base/src/resize-mixin.js';
+import type { SlotStylesMixinClass } from '@vaadin/component-base/src/slot-styles-mixin.js';
 
 export type FormLayoutLabelsPosition = 'aside' | 'top';
 
@@ -19,7 +19,7 @@ export type FormLayoutResponsiveStep = {
  */
 export declare function FormLayoutMixin<T extends Constructor<HTMLElement>>(
   base: T,
-): Constructor<ResizeMixinClass> & Constructor<FormLayoutMixinClass> & T;
+): Constructor<FormLayoutMixinClass> & Constructor<SlotStylesMixinClass> & T;
 
 export declare class FormLayoutMixinClass {
   /**
@@ -30,6 +30,14 @@ export declare class FormLayoutMixinClass {
    * with `minWidth` CSS length, `columns` number, and optional
    * `labelsPosition` string of `"aside"` or `"top"`. At least one item is required.
    *
+   * NOTE: Responsive steps are ignored in auto-responsive mode, which may be
+   * enabled explicitly via the `autoResponsive` property or implicitly
+   * if the following feature flag is set:
+   *
+   * ```
+   * window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true
+   * ```
+   *
    * #### Examples
    *
    * ```javascript
@@ -61,6 +69,107 @@ export declare class FormLayoutMixinClass {
    */
   responsiveSteps: FormLayoutResponsiveStep[];
 
+  /**
+   * When set to `true`, 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,
+   * `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.
+   *
+   * The auto-responsive mode is disabled by default. To enable it for an individual instance,
+   * use this property. Alternatively, if you want it to be enabled for all instances by default,
+   * enable the `defaultAutoResponsiveFormLayout` feature flag before `<vaadin-form-layout>`
+   * elements are added to the DOM:
+   *
+   * ```js
+   * window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true;
+   * ```
+   *
+   * @attr {boolean} auto-responsive
+   */
+  autoResponsive: boolean;
+
+  /**
+   * When `autoResponsive` is enabled, defines the width of each column.
+   * The value must be defined in CSS length units, e.g. `100px`.
+   *
+   * If the column width isn't explicitly set, it defaults to `12em`
+   * or `--vaadin-field-default-width` if that CSS property is defined.
+   *
+   * @attr {string} column-width
+   */
+  columnWidth: string;
+
+  /**
+   * 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: number;
+
+  /**
+   * 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.
+   *
+   * The default value is `false`.
+   *
+   * @attr {boolean} auto-rows
+   */
+  autoRows: boolean;
+
+  /**
+   * 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 a side label, the component will automatically switch labels to their
+   * default position above the fields.
+   *
+   * The default value is `false`.
+   *
+   * 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: boolean;
+
+  /**
+   * When `autoResponsive` is enabled, specifies whether the columns should expand
+   * in width to evenly fill any remaining space after all columns have been created.
+   *
+   * The default value is `false`.
+   *
+   * @attr {boolean} expand-columns
+   */
+  expandColumns: boolean;
+
+  /**
+   * 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: boolean;
+
   /**
    * Update the layout.
    */

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 {
         /**
@@ -37,6 +32,14 @@ export const FormLayoutMixin = (superClass) =>
          * with `minWidth` CSS length, `columns` number, and optional
          * `labelsPosition` string of `"aside"` or `"top"`. At least one item is required.
          *
+         * NOTE: Responsive steps are ignored in auto-responsive mode, which may be
+         * enabled explicitly via the `autoResponsive` property or implicitly
+         * if the following feature flag is set:
+         *
+         * ```
+         * window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true
+         * ```
+         *
          * #### Examples
          *
          * ```javascript
@@ -77,100 +80,198 @@ export const FormLayoutMixin = (superClass) =>
               { minWidth: '40em', columns: 2 },
             ];
           },
-          observer: '_responsiveStepsChanged',
+          observer: '__responsiveStepsChanged',
           sync: true,
         },
 
         /**
-         * Current number of columns in the layout
-         * @private
+         * When set to `true`, 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,
+         * `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.
+         *
+         * The auto-responsive mode is disabled by default. To enable it for an individual instance,
+         * use this property. Alternatively, if you want it to be enabled for all instances by default,
+         * enable the `defaultAutoResponsiveFormLayout` feature flag before `<vaadin-form-layout>`
+         * elements are added to the DOM:
+         *
+         * ```js
+         * window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout = true;
+         * ```
+         *
+         * @attr {boolean} auto-responsive
          */
-        _columnCount: {
+        autoResponsive: {
+          type: Boolean,
+          sync: true,
+          value: () => {
+            if (
+              window.Vaadin &&
+              window.Vaadin.featureFlags &&
+              window.Vaadin.featureFlags.defaultAutoResponsiveFormLayout
+            ) {
+              return true;
+            }
+
+            return false;
+          },
+          reflectToAttribute: true,
+        },
+
+        /**
+         * When `autoResponsive` is enabled, defines the width of each column.
+         * The value must be defined in CSS length units, e.g. `100px`.
+         *
+         * If the column width isn't explicitly set, it defaults to `12em`
+         * or `--vaadin-field-default-width` if that CSS property is defined.
+         *
+         * @attr {string} column-width
+         */
+        columnWidth: {
+          type: String,
+          sync: true,
+        },
+
+        /**
+         * 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,
+        },
+
+        /**
+         * 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.
+         *
+         * The default value is `false`.
+         *
+         * @attr {boolean} auto-rows
+         */
+        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 a side label, the component will automatically switch labels to their
+         * default position above the fields.
+         *
+         * The default value is `false`.
+         *
+         * 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 all columns have been created.
+         *
+         * The default value is `false`.
+         *
+         * @attr {boolean} expand-columns
+         */
+        expandColumns: {
+          type: Boolean,
+          sync: true,
+          value: false,
+          reflectToAttribute: true,
         },
 
         /**
-         * Indicates that labels are on top
-         * @private
+         * 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
          */
-        _labelsOnTop: {
+        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 +285,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();
     }
   };