@vaadin/form-layout 24.7.2 → 24.8.0-alpha10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/form-layout",
-  "version": "24.7.2",
+  "version": "24.8.0-alpha10",
   "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.2",
-    "@vaadin/component-base": "~24.7.2",
-    "@vaadin/vaadin-lumo-styles": "~24.7.2",
-    "@vaadin/vaadin-material-styles": "~24.7.2",
-    "@vaadin/vaadin-themable-mixin": "~24.7.2",
+    "@vaadin/a11y-base": "24.8.0-alpha10",
+    "@vaadin/component-base": "24.8.0-alpha10",
+    "@vaadin/vaadin-lumo-styles": "24.8.0-alpha10",
+    "@vaadin/vaadin-material-styles": "24.8.0-alpha10",
+    "@vaadin/vaadin-themable-mixin": "24.8.0-alpha10",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "~24.7.2",
-    "@vaadin/custom-field": "~24.7.2",
-    "@vaadin/test-runner-commands": "~24.7.2",
+    "@vaadin/chai-plugins": "24.8.0-alpha10",
+    "@vaadin/custom-field": "24.8.0-alpha10",
+    "@vaadin/test-runner-commands": "24.8.0-alpha10",
     "@vaadin/testing-helpers": "^1.1.0",
-    "@vaadin/text-field": "~24.7.2",
+    "@vaadin/text-field": "24.8.0-alpha10",
     "sinon": "^18.0.0"
   },
   "web-types": [
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "b9ad056bb7367f9cfcb44eac20e12c8c998ff979"
+  "gitHead": "f8c79ffc67eccc3ade226dfe52fbf7d3d46428cf"
 }

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,182 @@
+/**
+ * @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.js';
+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');
+    });
+
+    if (props.columnWidth) {
+      host.style.setProperty('--_column-width', props.columnWidth);
+    } else {
+      host.style.removeProperty('--_column-width');
+    }
+
+    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,255 @@
+/**
+ * @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.js';
+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 */
+  disconnect() {
+    if (!this.isConnected) {
+      return;
+    }
+
+    super.disconnect();
+
+    const { host } = this;
+    host.$.layout.style.removeProperty('opacity');
+    [...host.children].forEach((child) => {
+      child.style.removeProperty('width');
+      child.style.removeProperty('margin-left');
+      child.style.removeProperty('margin-right');
+      child.removeAttribute('label-position');
+    });
+  }
+
+  /** @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() {
+    if (!this.isConnected) {
+      return;
+    }
+
+    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-item-mixin.js

@@ -17,7 +17,8 @@ export const FormItemMixin = (superClass) =>
   class extends superClass {
     constructor() {
       super();
-      this.__updateInvalidState = this.__updateInvalidState.bind(this);
+
+      this.__onFieldInteraction = this.__onFieldInteraction.bind(this);
 
       /**
        * An observer for a field node to reflect its `required` and `invalid` attributes to the component.
@@ -25,7 +26,7 @@ export const FormItemMixin = (superClass) =>
        * @type {MutationObserver}
        * @private
        */
-      this.__fieldNodeObserver = new MutationObserver(() => this.__updateRequiredState(this.__fieldNode.required));
+      this.__fieldNodeObserver = new MutationObserver(() => this.__synchronizeAttributes());
 
       /**
        * The first label node in the label slot.
@@ -44,6 +45,8 @@ export const FormItemMixin = (superClass) =>
        * @private
        */
       this.__fieldNode = null;
+
+      this.__isFieldDirty = false;
     }
 
     /** @protected */
@@ -122,11 +125,6 @@ export const FormItemMixin = (superClass) =>
       }
     }
 
-    /** @private */
-    __getValidateFunction(field) {
-      return field.validate || field.checkValidity;
-    }
-
     /**
      * A `slotchange` event handler for the label slot.
      *
@@ -178,9 +176,11 @@ export const FormItemMixin = (superClass) =>
       if (this.__fieldNode) {
         // Discard the old field
         this.__unlinkLabelFromField(this.__fieldNode);
-        this.__updateRequiredState(false);
         this.__fieldNodeObserver.disconnect();
+        this.__fieldNode.removeEventListener('blur', this.__onFieldInteraction);
+        this.__fieldNode.removeEventListener('change', this.__onFieldInteraction);
         this.__fieldNode = null;
+        this.__isFieldDirty = false;
       }
 
       const fieldNodes = this.$.contentSlot.assignedElements();
@@ -191,37 +191,43 @@ Please wrap fields with a <vaadin-custom-field> instead.`,
         );
       }
 
-      const newFieldNode = fieldNodes.find((field) => {
-        return !!this.__getValidateFunction(field);
-      });
+      const newFieldNode = fieldNodes.find((field) => field.validate || field.checkValidity);
       if (newFieldNode) {
         this.__fieldNode = newFieldNode;
-        this.__updateRequiredState(this.__fieldNode.required);
-        this.__fieldNodeObserver.observe(this.__fieldNode, { attributes: true, attributeFilter: ['required'] });
+        this.__fieldNode.addEventListener('blur', this.__onFieldInteraction);
+        this.__fieldNode.addEventListener('change', this.__onFieldInteraction);
+        this.__fieldNodeObserver.observe(this.__fieldNode, {
+          attributes: true,
+          attributeFilter: ['required', 'invalid'],
+        });
 
         if (this.__labelNode) {
           this.__linkLabelToField(this.__fieldNode);
         }
       }
+
+      this.__synchronizeAttributes();
     }
 
     /** @private */
-    __updateRequiredState(required) {
-      if (required) {
-        this.setAttribute('required', '');
-        this.__fieldNode.addEventListener('blur', this.__updateInvalidState);
-        this.__fieldNode.addEventListener('change', this.__updateInvalidState);
-      } else {
-        this.removeAttribute('invalid');
-        this.removeAttribute('required');
-        this.__fieldNode.removeEventListener('blur', this.__updateInvalidState);
-        this.__fieldNode.removeEventListener('change', this.__updateInvalidState);
-      }
+    __onFieldInteraction() {
+      this.__isFieldDirty = true;
+      this.__synchronizeAttributes();
     }
 
     /** @private */
-    __updateInvalidState() {
-      const isValid = this.__getValidateFunction(this.__fieldNode).call(this.__fieldNode);
-      this.toggleAttribute('invalid', isValid === false);
+    __synchronizeAttributes() {
+      const field = this.__fieldNode;
+      if (!field) {
+        this.removeAttribute('required');
+        this.removeAttribute('invalid');
+        return;
+      }
+
+      this.toggleAttribute('required', field.hasAttribute('required'));
+      this.toggleAttribute(
+        'invalid',
+        field.hasAttribute('invalid') || (field.matches(':invalid') && this.__isFieldDirty),
+      );
     }
   };