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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/form-layout",
-  "version": "24.7.0-rc1",
+  "version": "24.8.0-alpha1",
   "publishConfig": {
     "access": "public"
   },
@@ -37,24 +37,24 @@
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/a11y-base": "24.7.0-rc1",
-    "@vaadin/component-base": "24.7.0-rc1",
-    "@vaadin/vaadin-lumo-styles": "24.7.0-rc1",
-    "@vaadin/vaadin-material-styles": "24.7.0-rc1",
-    "@vaadin/vaadin-themable-mixin": "24.7.0-rc1",
+    "@vaadin/a11y-base": "24.8.0-alpha1",
+    "@vaadin/component-base": "24.8.0-alpha1",
+    "@vaadin/vaadin-lumo-styles": "24.8.0-alpha1",
+    "@vaadin/vaadin-material-styles": "24.8.0-alpha1",
+    "@vaadin/vaadin-themable-mixin": "24.8.0-alpha1",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "24.7.0-rc1",
-    "@vaadin/custom-field": "24.7.0-rc1",
-    "@vaadin/test-runner-commands": "24.7.0-rc1",
+    "@vaadin/chai-plugins": "24.8.0-alpha1",
+    "@vaadin/custom-field": "24.8.0-alpha1",
+    "@vaadin/test-runner-commands": "24.8.0-alpha1",
     "@vaadin/testing-helpers": "^1.1.0",
-    "@vaadin/text-field": "24.7.0-rc1",
+    "@vaadin/text-field": "24.8.0-alpha1",
     "sinon": "^18.0.0"
   },
   "web-types": [
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "28f6d361ebf39070c0961cee75ee6c14089109b2"
+  "gitHead": "dfec8767c5d1c343ae689c93429c3364f4182f76"
 }

package/src/layouts/abstract-layout.js

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * An abstract class for layout implementation. Not intended for public use.
+ *
+ * @private
+ */
+export class AbstractLayout {
+  /**
+   * @param {HTMLElement} host
+   * @param {{ mutationObserverOptions: MutationObserverInit }} config
+   */
+  constructor(host, config) {
+    this.host = host;
+    this.props = {};
+    this.config = config;
+    this.isConnected = false;
+
+    /** @private */
+    this.__resizeObserver = new ResizeObserver((entries) => setTimeout(() => this._onResize(entries)));
+
+    /** @private */
+    this.__mutationObserver = new MutationObserver((records) => this._onMutation(records));
+  }
+
+  /**
+   * Connects the layout to the host element.
+   */
+  connect() {
+    if (this.isConnected) {
+      return;
+    }
+
+    this.isConnected = true;
+    this.__resizeObserver.observe(this.host);
+    this.__mutationObserver.observe(this.host, this.config.mutationObserverOptions);
+  }
+
+  /**
+   * Disconnects the layout from the host element.
+   */
+  disconnect() {
+    if (!this.isConnected) {
+      return;
+    }
+
+    this.isConnected = false;
+    this.__resizeObserver.disconnect();
+    this.__mutationObserver.disconnect();
+  }
+
+  /**
+   * Sets the properties of the layout controller.
+   */
+  setProps(props) {
+    this.props = props;
+  }
+
+  /**
+   * Updates the layout based on the current properties.
+   */
+  updateLayout() {
+    // To be implemented
+  }
+
+  /**
+   * @param {ResizeObserverEntry[]} _entries
+   * @protected
+   */
+  _onResize(_entries) {
+    // To be implemented
+  }
+
+  /**
+   * @param {MutationRecord[]} _records
+   * @protected
+   */
+  _onMutation(_records) {
+    // To be implemented
+  }
+}

package/src/layouts/auto-responsive-layout.js

@@ -0,0 +1,177 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 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';
+import { AbstractLayout } from './abstract-layout.js';
+
+/**
+ * Check if the node is a line break element.
+ *
+ * @param {HTMLElement} el
+ * @return {boolean}
+ */
+function isBreakLine(el) {
+  return el.localName === 'br';
+}
+
+/**
+ * A class that implements the auto-responsive layout algorithm.
+ * Not intended for public use.
+ *
+ * @private
+ */
+export class AutoResponsiveLayout extends AbstractLayout {
+  constructor(host) {
+    super(host, {
+      mutationObserverOptions: {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: ['colspan', 'data-colspan', 'hidden'],
+      },
+    });
+  }
+
+  /** @override */
+  connect() {
+    if (this.isConnected) {
+      return;
+    }
+
+    super.connect();
+
+    this.updateLayout();
+  }
+
+  /** @override */
+  disconnect() {
+    if (!this.isConnected) {
+      return;
+    }
+
+    super.disconnect();
+
+    const { host } = this;
+    host.style.removeProperty('--_column-width');
+    host.style.removeProperty('--_max-columns');
+    host.$.layout.removeAttribute('fits-labels-aside');
+    host.$.layout.style.removeProperty('--_grid-rendered-column-count');
+
+    this.__children.forEach((child) => {
+      child.style.removeProperty('--_grid-colstart');
+      child.style.removeProperty('--_grid-colspan');
+    });
+  }
+
+  /** @override */
+  setProps(props) {
+    super.setProps(props);
+
+    if (this.isConnected) {
+      this.updateLayout();
+    }
+  }
+
+  /** @override */
+  updateLayout() {
+    const { host, props } = this;
+    if (!this.isConnected || isElementHidden(host)) {
+      return;
+    }
+
+    let columnCount = 0;
+    let maxColumns = 0;
+
+    const children = this.__children;
+    children
+      .filter((child) => isBreakLine(child) || !isElementHidden(child))
+      .forEach((child, index, children) => {
+        const prevChild = children[index - 1];
+
+        if (isBreakLine(child)) {
+          columnCount = 0;
+          return;
+        }
+
+        if (
+          (prevChild && prevChild.parentElement !== child.parentElement) ||
+          (!props.autoRows && child.parentElement === host)
+        ) {
+          columnCount = 0;
+        }
+
+        if (props.autoRows && columnCount === 0) {
+          child.style.setProperty('--_grid-colstart', 1);
+        } else {
+          child.style.removeProperty('--_grid-colstart');
+        }
+
+        const colspan = child.getAttribute('colspan') || child.getAttribute('data-colspan');
+        if (colspan) {
+          columnCount += parseInt(colspan);
+          child.style.setProperty('--_grid-colspan', colspan);
+        } else {
+          columnCount += 1;
+          child.style.removeProperty('--_grid-colspan');
+        }
+
+        maxColumns = Math.max(maxColumns, columnCount);
+      });
+
+    children.filter(isElementHidden).forEach((child) => {
+      child.style.removeProperty('--_grid-colstart');
+    });
+
+    host.style.setProperty('--_column-width', props.columnWidth);
+    host.style.setProperty('--_max-columns', Math.min(props.maxColumns, maxColumns));
+
+    host.$.layout.toggleAttribute('fits-labels-aside', this.props.labelsAside && this.__fitsLabelsAside);
+    host.$.layout.style.setProperty('--_grid-rendered-column-count', this.__renderedColumnCount);
+  }
+
+  /** @override */
+  _onResize() {
+    this.updateLayout();
+  }
+
+  /** @override */
+  _onMutation(records) {
+    const shouldUpdateLayout = records.some(({ target }) => {
+      return (
+        target === this.host ||
+        target.parentElement === this.host ||
+        target.parentElement.localName === 'vaadin-form-row'
+      );
+    });
+    if (shouldUpdateLayout) {
+      this.updateLayout();
+    }
+  }
+
+  /** @private */
+  get __children() {
+    return [...this.host.children].flatMap((child) => {
+      return child.localName === 'vaadin-form-row' ? [...child.children] : child;
+    });
+  }
+
+  /** @private */
+  get __renderedColumnCount() {
+    // Calculate the number of rendered columns, excluding CSS grid auto columns (0px)
+    const { gridTemplateColumns } = getComputedStyle(this.host.$.layout);
+    return gridTemplateColumns.split(' ').filter((width) => width !== '0px').length;
+  }
+
+  /** @private */
+  get __columnWidthWithLabelsAside() {
+    const { backgroundPositionY } = getComputedStyle(this.host.$.layout, '::before');
+    return parseFloat(backgroundPositionY);
+  }
+
+  /** @private */
+  get __fitsLabelsAside() {
+    return this.host.offsetWidth >= this.__columnWidthWithLabelsAside;
+  }
+}

package/src/layouts/responsive-steps-layout.js

@@ -0,0 +1,233 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 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';
+import { AbstractLayout } from './abstract-layout.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);
+}
+
+function naturalNumberOrOne(n) {
+  if (typeof n === 'number' && n >= 1 && n < Infinity) {
+    return Math.floor(n);
+  }
+  return 1;
+}
+
+/**
+ * A class that implements the layout algorithm based on responsive steps.
+ * Not intended for public use.
+ *
+ * @private
+ */
+export class ResponsiveStepsLayout extends AbstractLayout {
+  constructor(host) {
+    super(host, {
+      mutationObserverOptions: {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: ['colspan', 'data-colspan', 'hidden'],
+      },
+    });
+  }
+
+  /** @override */
+  connect() {
+    if (this.isConnected) {
+      return;
+    }
+
+    super.connect();
+
+    this.__selectResponsiveStep();
+    this.updateLayout();
+
+    requestAnimationFrame(() => this.__selectResponsiveStep());
+    requestAnimationFrame(() => this.updateLayout());
+  }
+
+  /** @override */
+  setProps(props) {
+    const { responsiveSteps } = props;
+    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 (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.`,
+        );
+      }
+    });
+
+    super.setProps(props);
+
+    if (this.isConnected) {
+      this.__selectResponsiveStep();
+      this.updateLayout();
+    }
+  }
+
+  /** @override */
+  updateLayout() {
+    const { host } = this;
+
+    // Do not update layout when invisible
+    if (!this.isConnected || isElementHidden(host)) {
+      return;
+    }
+
+    /*
+      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(host);
+    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 = host.offsetWidth;
+
+    let col = 0;
+    Array.from(host.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 = 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');
+          }
+        }
+      });
+  }
+
+  /** @override */
+  _onResize() {
+    const { host } = this;
+    if (isElementHidden(host)) {
+      host.$.layout.style.opacity = '0';
+      return;
+    }
+
+    this.__selectResponsiveStep();
+    this.updateLayout();
+
+    host.$.layout.style.opacity = '';
+  }
+
+  /** @override */
+  _onMutation(records) {
+    const shouldUpdateLayout = records.some(({ target }) => {
+      return target === this.host || target.parentElement === this.host;
+    });
+    if (shouldUpdateLayout) {
+      this.updateLayout();
+    }
+  }
+
+  /** @private */
+  __selectResponsiveStep() {
+    const { host, props } = this;
+    // Iterate through responsiveSteps and choose the step
+    let selectedStep;
+    const tmpStyleProp = 'background-position';
+    props.responsiveSteps.forEach((step) => {
+      // Convert minWidth to px units for comparison
+      host.$.layout.style.setProperty(tmpStyleProp, step.minWidth);
+      const stepMinWidthPx = parseFloat(getComputedStyle(host.$.layout).getPropertyValue(tmpStyleProp));
+
+      // Compare step min-width with the host width, select the passed step
+      if (stepMinWidthPx <= host.offsetWidth) {
+        selectedStep = step;
+      }
+    });
+    host.$.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';
+    }
+  }
+}

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 {
   /**
@@ -61,6 +61,87 @@ export declare class FormLayoutMixinClass {
    */
   responsiveSteps: FormLayoutResponsiveStep[];
 
+  /**
+   * 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: boolean;
+
+  /**
+   * 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
+   */
+  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.
+   *
+   * @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 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: boolean;
+
+  /**
+   * 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: 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.
    */