@vaadin/form-layout 24.7.0-alpha1 → 24.7.0-alpha3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/form-layout",
-  "version": "24.7.0-alpha1",
+  "version": "24.7.0-alpha3",
   "publishConfig": {
     "access": "public"
   },
@@ -35,23 +35,24 @@
     "polymer"
   ],
   "dependencies": {
+    "@open-wc/dedupe-mixin": "^1.3.0",
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/a11y-base": "24.7.0-alpha1",
-    "@vaadin/component-base": "24.7.0-alpha1",
-    "@vaadin/vaadin-lumo-styles": "24.7.0-alpha1",
-    "@vaadin/vaadin-material-styles": "24.7.0-alpha1",
-    "@vaadin/vaadin-themable-mixin": "24.7.0-alpha1"
+    "@vaadin/a11y-base": "24.7.0-alpha3",
+    "@vaadin/component-base": "24.7.0-alpha3",
+    "@vaadin/vaadin-lumo-styles": "24.7.0-alpha3",
+    "@vaadin/vaadin-material-styles": "24.7.0-alpha3",
+    "@vaadin/vaadin-themable-mixin": "24.7.0-alpha3"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "24.7.0-alpha1",
-    "@vaadin/custom-field": "24.7.0-alpha1",
-    "@vaadin/testing-helpers": "^1.0.0",
-    "@vaadin/text-field": "24.7.0-alpha1",
+    "@vaadin/chai-plugins": "24.7.0-alpha3",
+    "@vaadin/custom-field": "24.7.0-alpha3",
+    "@vaadin/testing-helpers": "^1.1.0",
+    "@vaadin/text-field": "24.7.0-alpha3",
     "sinon": "^18.0.0"
   },
   "web-types": [
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "04be941c9a7b659871c97f31b9cc3ffd7528087b"
+  "gitHead": "dd5cfad6c9b54e676f5b10dffba2233775378f40"
 }

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

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2024 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+
+/**
+ * A mixin providing common form-item functionality.
+ */
+export declare function FormItemMixin<T extends Constructor<HTMLElement>>(base: T): Constructor<FormItemMixinClass> & T;
+
+export declare class FormItemMixinClass {
+  /**
+   * Returns a target element to add ARIA attributes to for a field.
+   *
+   * - For Vaadin field components, the method returns an element
+   * obtained through the `ariaTarget` property defined in `FieldMixin`.
+   * - In other cases, the method returns the field element itself.
+   */
+  protected _getFieldAriaTarget(field: HTMLElement): HTMLElement;
+}

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

@@ -0,0 +1,192 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2024 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { addValueToAttribute, removeValueFromAttribute } from '@vaadin/component-base/src/dom-utils.js';
+import { generateUniqueId } from '@vaadin/component-base/src/unique-id-utils.js';
+
+/**
+ * @polymerMixin
+ */
+export const FormItemMixin = (superClass) =>
+  class extends superClass {
+    constructor() {
+      super();
+      this.__updateInvalidState = this.__updateInvalidState.bind(this);
+
+      /**
+       * An observer for a field node to reflect its `required` and `invalid` attributes to the component.
+       *
+       * @type {MutationObserver}
+       * @private
+       */
+      this.__fieldNodeObserver = new MutationObserver(() => this.__updateRequiredState(this.__fieldNode.required));
+
+      /**
+       * The first label node in the label slot.
+       *
+       * @type {HTMLElement | null}
+       * @private
+       */
+      this.__labelNode = null;
+
+      /**
+       * The first field node in the content slot.
+       *
+       * An element is considered a field when it has the `checkValidity` or `validate` method.
+       *
+       * @type {HTMLElement | null}
+       * @private
+       */
+      this.__fieldNode = null;
+    }
+
+    /**
+     * Returns a target element to add ARIA attributes to for a field.
+     *
+     * - For Vaadin field components, the method returns an element
+     * obtained through the `ariaTarget` property defined in `FieldMixin`.
+     * - In other cases, the method returns the field element itself.
+     *
+     * @param {HTMLElement} field
+     * @protected
+     */
+    _getFieldAriaTarget(field) {
+      return field.ariaTarget || field;
+    }
+
+    /**
+     * Links the label to a field by adding the label id to
+     * the `aria-labelledby` attribute of the field's ARIA target element.
+     *
+     * @param {HTMLElement} field
+     * @private
+     */
+    __linkLabelToField(field) {
+      addValueToAttribute(this._getFieldAriaTarget(field), 'aria-labelledby', this.__labelId);
+    }
+
+    /**
+     * Unlinks the label from a field by removing the label id from
+     * the `aria-labelledby` attribute of the field's ARIA target element.
+     *
+     * @param {HTMLElement} field
+     * @private
+     */
+    __unlinkLabelFromField(field) {
+      removeValueFromAttribute(this._getFieldAriaTarget(field), 'aria-labelledby', this.__labelId);
+    }
+
+    /** @private */
+    __onLabelClick() {
+      const fieldNode = this.__fieldNode;
+      if (fieldNode) {
+        fieldNode.focus();
+        fieldNode.click();
+      }
+    }
+
+    /** @private */
+    __getValidateFunction(field) {
+      return field.validate || field.checkValidity;
+    }
+
+    /**
+     * A `slotchange` event handler for the label slot.
+     *
+     * - Ensures the label id is only assigned to the first label node.
+     * - Ensures the label node is linked to the first field node via the `aria-labelledby` attribute
+     * if both nodes are provided, and unlinked otherwise.
+     *
+     * @private
+     */
+    __onLabelSlotChange() {
+      if (this.__labelNode) {
+        this.__labelNode = null;
+
+        if (this.__fieldNode) {
+          this.__unlinkLabelFromField(this.__fieldNode);
+        }
+      }
+
+      const newLabelNode = this.$.labelSlot.assignedElements()[0];
+      if (newLabelNode) {
+        this.__labelNode = newLabelNode;
+
+        if (this.__labelNode.id) {
+          // The new label node already has an id. Let's use it.
+          this.__labelId = this.__labelNode.id;
+        } else {
+          // The new label node doesn't have an id yet. Generate a unique one.
+          this.__labelId = `label-${this.localName}-${generateUniqueId()}`;
+          this.__labelNode.id = this.__labelId;
+        }
+
+        if (this.__fieldNode) {
+          this.__linkLabelToField(this.__fieldNode);
+        }
+      }
+    }
+
+    /**
+     * A `slotchange` event handler for the content slot.
+     *
+     * - Ensures the label node is only linked to the first field node via the `aria-labelledby` attribute.
+     * - Sets up an observer for the `required` attribute changes on the first field
+     * to reflect the attribute on the component. Ensures the observer is disconnected from the field
+     * as soon as it is removed or replaced by another one.
+     *
+     * @private
+     */
+    __onContentSlotChange() {
+      if (this.__fieldNode) {
+        // Discard the old field
+        this.__unlinkLabelFromField(this.__fieldNode);
+        this.__updateRequiredState(false);
+        this.__fieldNodeObserver.disconnect();
+        this.__fieldNode = null;
+      }
+
+      const fieldNodes = this.$.contentSlot.assignedElements();
+      if (fieldNodes.length > 1) {
+        console.warn(
+          `WARNING: Since Vaadin 23, placing multiple fields directly to a <vaadin-form-item> is deprecated.
+Please wrap fields with a <vaadin-custom-field> instead.`,
+        );
+      }
+
+      const newFieldNode = fieldNodes.find((field) => {
+        return !!this.__getValidateFunction(field);
+      });
+      if (newFieldNode) {
+        this.__fieldNode = newFieldNode;
+        this.__updateRequiredState(this.__fieldNode.required);
+        this.__fieldNodeObserver.observe(this.__fieldNode, { attributes: true, attributeFilter: ['required'] });
+
+        if (this.__labelNode) {
+          this.__linkLabelToField(this.__fieldNode);
+        }
+      }
+    }
+
+    /** @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);
+      }
+    }
+
+    /** @private */
+    __updateInvalidState() {
+      const isValid = this.__getValidateFunction(this.__fieldNode).call(this.__fieldNode);
+      this.toggleAttribute('invalid', isValid === false);
+    }
+  };

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

@@ -4,6 +4,7 @@
  * 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';
+import { FormItemMixin } from './vaadin-form-item-mixin.js';
 
 /**
  * `<vaadin-form-item>` is a Web Component providing labelled form item wrapper
@@ -84,16 +85,7 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  */
-declare class FormItem extends ThemableMixin(HTMLElement) {
-  /**
-   * Returns a target element to add ARIA attributes to for a field.
-   *
-   * - For Vaadin field components, the method returns an element
-   * obtained through the `ariaTarget` property defined in `FieldMixin`.
-   * - In other cases, the method returns the field element itself.
-   */
-  protected _getFieldAriaTarget(field: HTMLElement): HTMLElement;
-}
+declare class FormItem extends FormItemMixin(ThemableMixin(HTMLElement)) {}
 
 declare global {
   interface HTMLElementTagNameMap {

package/src/vaadin-form-item.js

@@ -5,9 +5,11 @@
  */
 import { html, PolymerElement } from '@polymer/polymer/polymer-element.js';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
-import { addValueToAttribute, removeValueFromAttribute } from '@vaadin/component-base/src/dom-utils.js';
-import { generateUniqueId } from '@vaadin/component-base/src/unique-id-utils.js';
-import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { registerStyles, ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { FormItemMixin } from './vaadin-form-item-mixin.js';
+import { formItemStyles } from './vaadin-form-layout-styles.js';
+
+registerStyles('vaadin-form-item', formItemStyles, { moduleId: 'vaadin-form-item-styles' });
 
 /**
  * `<vaadin-form-item>` is a Web Component providing labelled form item wrapper
@@ -90,52 +92,16 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  *
  * @customElement
  * @extends HTMLElement
+ * @mixes FormItemMixin
  * @mixes ThemableMixin
  */
-class FormItem extends ThemableMixin(PolymerElement) {
+class FormItem extends FormItemMixin(ThemableMixin(PolymerElement)) {
+  static get is() {
+    return 'vaadin-form-item';
+  }
+
   static get template() {
     return html`
-      <style>
-        :host {
-          display: inline-flex;
-          flex-direction: row;
-          align-items: baseline;
-          margin: calc(0.5 * var(--vaadin-form-item-row-spacing, 1em)) 0;
-        }
-
-        :host([label-position='top']) {
-          flex-direction: column;
-          align-items: stretch;
-        }
-
-        :host([hidden]) {
-          display: none !important;
-        }
-
-        #label {
-          width: var(--vaadin-form-item-label-width, 8em);
-          flex: 0 0 auto;
-        }
-
-        :host([label-position='top']) #label {
-          width: auto;
-        }
-
-        #spacing {
-          width: var(--vaadin-form-item-label-spacing, 1em);
-          flex: 0 0 auto;
-        }
-
-        #content {
-          flex: 1 1 auto;
-        }
-
-        #content ::slotted(.full-width) {
-          box-sizing: border-box;
-          width: 100%;
-          min-width: 0;
-        }
-      </style>
       <div id="label" part="label" on-click="__onLabelClick">
         <slot name="label" id="labelSlot" on-slotchange="__onLabelSlotChange"></slot>
         <span part="required-indicator" aria-hidden="true"></span>
@@ -146,189 +112,6 @@ class FormItem extends ThemableMixin(PolymerElement) {
       </div>
     `;
   }
-
-  static get is() {
-    return 'vaadin-form-item';
-  }
-
-  constructor() {
-    super();
-    this.__updateInvalidState = this.__updateInvalidState.bind(this);
-
-    /**
-     * An observer for a field node to reflect its `required` and `invalid` attributes to the component.
-     *
-     * @type {MutationObserver}
-     * @private
-     */
-    this.__fieldNodeObserver = new MutationObserver(() => this.__updateRequiredState(this.__fieldNode.required));
-
-    /**
-     * The first label node in the label slot.
-     *
-     * @type {HTMLElement | null}
-     * @private
-     */
-    this.__labelNode = null;
-
-    /**
-     * The first field node in the content slot.
-     *
-     * An element is considered a field when it has the `checkValidity` or `validate` method.
-     *
-     * @type {HTMLElement | null}
-     * @private
-     */
-    this.__fieldNode = null;
-  }
-
-  /**
-   * Returns a target element to add ARIA attributes to for a field.
-   *
-   * - For Vaadin field components, the method returns an element
-   * obtained through the `ariaTarget` property defined in `FieldMixin`.
-   * - In other cases, the method returns the field element itself.
-   *
-   * @param {HTMLElement} field
-   * @protected
-   */
-  _getFieldAriaTarget(field) {
-    return field.ariaTarget || field;
-  }
-
-  /**
-   * Links the label to a field by adding the label id to
-   * the `aria-labelledby` attribute of the field's ARIA target element.
-   *
-   * @param {HTMLElement} field
-   * @private
-   */
-  __linkLabelToField(field) {
-    addValueToAttribute(this._getFieldAriaTarget(field), 'aria-labelledby', this.__labelId);
-  }
-
-  /**
-   * Unlinks the label from a field by removing the label id from
-   * the `aria-labelledby` attribute of the field's ARIA target element.
-   *
-   * @param {HTMLElement} field
-   * @private
-   */
-  __unlinkLabelFromField(field) {
-    removeValueFromAttribute(this._getFieldAriaTarget(field), 'aria-labelledby', this.__labelId);
-  }
-
-  /** @private */
-  __onLabelClick() {
-    const fieldNode = this.__fieldNode;
-    if (fieldNode) {
-      fieldNode.focus();
-      fieldNode.click();
-    }
-  }
-
-  /** @private */
-  __getValidateFunction(field) {
-    return field.validate || field.checkValidity;
-  }
-
-  /**
-   * A `slotchange` event handler for the label slot.
-   *
-   * - Ensures the label id is only assigned to the first label node.
-   * - Ensures the label node is linked to the first field node via the `aria-labelledby` attribute
-   * if both nodes are provided, and unlinked otherwise.
-   *
-   * @private
-   */
-  __onLabelSlotChange() {
-    if (this.__labelNode) {
-      this.__labelNode = null;
-
-      if (this.__fieldNode) {
-        this.__unlinkLabelFromField(this.__fieldNode);
-      }
-    }
-
-    const newLabelNode = this.$.labelSlot.assignedElements()[0];
-    if (newLabelNode) {
-      this.__labelNode = newLabelNode;
-
-      if (this.__labelNode.id) {
-        // The new label node already has an id. Let's use it.
-        this.__labelId = this.__labelNode.id;
-      } else {
-        // The new label node doesn't have an id yet. Generate a unique one.
-        this.__labelId = `label-${this.localName}-${generateUniqueId()}`;
-        this.__labelNode.id = this.__labelId;
-      }
-
-      if (this.__fieldNode) {
-        this.__linkLabelToField(this.__fieldNode);
-      }
-    }
-  }
-
-  /**
-   * A `slotchange` event handler for the content slot.
-   *
-   * - Ensures the label node is only linked to the first field node via the `aria-labelledby` attribute.
-   * - Sets up an observer for the `required` attribute changes on the first field
-   * to reflect the attribute on the component. Ensures the observer is disconnected from the field
-   * as soon as it is removed or replaced by another one.
-   *
-   * @private
-   */
-  __onContentSlotChange() {
-    if (this.__fieldNode) {
-      // Discard the old field
-      this.__unlinkLabelFromField(this.__fieldNode);
-      this.__updateRequiredState(false);
-      this.__fieldNodeObserver.disconnect();
-      this.__fieldNode = null;
-    }
-
-    const fieldNodes = this.$.contentSlot.assignedElements();
-    if (fieldNodes.length > 1) {
-      console.warn(
-        `WARNING: Since Vaadin 23, placing multiple fields directly to a <vaadin-form-item> is deprecated.
-Please wrap fields with a <vaadin-custom-field> instead.`,
-      );
-    }
-
-    const newFieldNode = fieldNodes.find((field) => {
-      return !!this.__getValidateFunction(field);
-    });
-    if (newFieldNode) {
-      this.__fieldNode = newFieldNode;
-      this.__updateRequiredState(this.__fieldNode.required);
-      this.__fieldNodeObserver.observe(this.__fieldNode, { attributes: true, attributeFilter: ['required'] });
-
-      if (this.__labelNode) {
-        this.__linkLabelToField(this.__fieldNode);
-      }
-    }
-  }
-
-  /** @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);
-    }
-  }
-
-  /** @private */
-  __updateInvalidState() {
-    const isValid = this.__getValidateFunction(this.__fieldNode).call(this.__fieldNode);
-    this.toggleAttribute('invalid', isValid === false);
-  }
 }
 
 defineCustomElement(FormItem);

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

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2024 Vaadin Ltd.
+ * 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';
+
+export type FormLayoutLabelsPosition = 'aside' | 'top';
+
+export type FormLayoutResponsiveStep = {
+  minWidth?: string | 0;
+  columns: number;
+  labelsPosition?: FormLayoutLabelsPosition;
+};
+
+/**
+ * A mixin providing common form-layout functionality.
+ */
+export declare function FormLayoutMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<ResizeMixinClass> & Constructor<FormLayoutMixinClass> & T;
+
+export declare class FormLayoutMixinClass {
+  /**
+   * Allows specifying a responsive behavior with the number of columns
+   * and the label position depending on the layout width.
+   *
+   * Format: array of objects, each object defines one responsive step
+   * with `minWidth` CSS length, `columns` number, and optional
+   * `labelsPosition` string of `"aside"` or `"top"`. At least one item is required.
+   *
+   * #### Examples
+   *
+   * ```javascript
+   * formLayout.responsiveSteps = [{columns: 1}];
+   * // The layout is always a single column, labels aside.
+   * ```
+   *
+   * ```javascript
+   * formLayout.responsiveSteps = [
+   *   {minWidth: 0, columns: 1},
+   *   {minWidth: '40em', columns: 2}
+   * ];
+   * // Sets two responsive steps:
+   * // 1. When the layout width is < 40em, one column, labels aside.
+   * // 2. Width >= 40em, two columns, labels aside.
+   * ```
+   *
+   * ```javascript
+   * formLayout.responsiveSteps = [
+   *   {minWidth: 0, columns: 1, labelsPosition: 'top'},
+   *   {minWidth: '20em', columns: 1},
+   *   {minWidth: '40em', columns: 2}
+   * ];
+   * // Default value. Three responsive steps:
+   * // 1. Width < 20em, one column, labels on top.
+   * // 2. 20em <= width < 40em, one column, labels aside.
+   * // 3. Width >= 40em, two columns, labels aside.
+   * ```
+   */
+  responsiveSteps: FormLayoutResponsiveStep[];
+
+  /**
+   * Update the layout.
+   */
+  protected _updateLayout(): void;
+}