@vaadin/form-layout 22.0.1 → 23.0.0-alpha3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/form-layout",
-  "version": "22.0.1",
+  "version": "23.0.0-alpha3",
   "publishConfig": {
     "access": "public"
   },
@@ -32,18 +32,18 @@
     "polymer"
   ],
   "dependencies": {
-    "@polymer/iron-resizable-behavior": "^3.0.0",
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/component-base": "^22.0.1",
-    "@vaadin/vaadin-lumo-styles": "^22.0.1",
-    "@vaadin/vaadin-material-styles": "^22.0.1",
-    "@vaadin/vaadin-themable-mixin": "^22.0.1"
+    "@vaadin/component-base": "23.0.0-alpha3",
+    "@vaadin/vaadin-lumo-styles": "23.0.0-alpha3",
+    "@vaadin/vaadin-material-styles": "23.0.0-alpha3",
+    "@vaadin/vaadin-themable-mixin": "23.0.0-alpha3"
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
+    "@vaadin/custom-field": "23.0.0-alpha3",
     "@vaadin/testing-helpers": "^0.3.2",
-    "@vaadin/text-field": "^22.0.1",
+    "@vaadin/text-field": "23.0.0-alpha3",
     "sinon": "^9.2.1"
   },
-  "gitHead": "2b0a2bff0369d6020f7cc33ad35506aa2d1f6f68"
+  "gitHead": "490037919a9e054cc002c1b3be0c94a1603e1a44"
 }

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

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2017 - 2022 Vaadin Ltd.
  * 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';
@@ -9,7 +9,7 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  * `<vaadin-form-item>` is a Web Component providing labelled form item wrapper
  * for using inside `<vaadin-form-layout>`.
  *
- * `<vaadin-form-item>` accepts any number of children as the input content,
+ * `<vaadin-form-item>` accepts a single child as the input content,
  * and also has a separate named `label` slot:
  *
  * ```html
@@ -19,19 +19,6 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  * </vaadin-form-item>
  * ```
  *
- * Any content can be used. For instance, you can have multiple input elements
- * with surrounding text. The label can be an element of any type:
- *
- * ```html
- * <vaadin-form-item>
- *   <span slot="label">Date of Birth</span>
- *   <input placeholder="YYYY" size="4"> -
- *   <input placeholder="MM" size="2"> -
- *   <input placeholder="DD" size="2"><br>
- *   <em>Example: 1900-01-01</em>
- * </vaadin-form-item>
- * ```
- *
  * The label is optional and can be omitted:
  *
  * ```html
@@ -58,7 +45,7 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  * ### Input Width
  *
  * By default, `<vaadin-form-item>` does not manipulate the width of the slotted
- * input elements. Optionally you can stretch the child input element to fill
+ * input element. Optionally you can stretch the child input element to fill
  * the available width for the input content by adding the `full-width` class:
  *
  * ```html
@@ -97,7 +84,16 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  *
  * See [Styling Components](https://vaadin.com/docs/latest/ds/customization/styling-components) documentation.
  */
-declare class FormItem extends ThemableMixin(HTMLElement) {}
+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 global {
   interface HTMLElementTagNameMap {

package/src/vaadin-form-item.js

@@ -1,16 +1,17 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2017 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { html, PolymerElement } from '@polymer/polymer/polymer-element.js';
+import { addValueToAttribute, removeValueFromAttribute } from '@vaadin/field-base/src/utils.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 /**
  * `<vaadin-form-item>` is a Web Component providing labelled form item wrapper
  * for using inside `<vaadin-form-layout>`.
  *
- * `<vaadin-form-item>` accepts any number of children as the input content,
+ * `<vaadin-form-item>` accepts a single child as the input content,
  * and also has a separate named `label` slot:
  *
  * ```html
@@ -20,19 +21,6 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  * </vaadin-form-item>
  * ```
  *
- * Any content can be used. For instance, you can have multiple input elements
- * with surrounding text. The label can be an element of any type:
- *
- * ```html
- * <vaadin-form-item>
- *   <span slot="label">Date of Birth</span>
- *   <input placeholder="YYYY" size="4"> -
- *   <input placeholder="MM" size="2"> -
- *   <input placeholder="DD" size="2"><br>
- *   <em>Example: 1900-01-01</em>
- * </vaadin-form-item>
- * ```
- *
  * The label is optional and can be omitted:
  *
  * ```html
@@ -59,7 +47,7 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  * ### Input Width
  *
  * By default, `<vaadin-form-item>` does not manipulate the width of the slotted
- * input elements. Optionally you can stretch the child input element to fill
+ * input element. Optionally you can stretch the child input element to fill
  * the available width for the input content by adding the `full-width` class:
  *
  * ```html
@@ -145,12 +133,13 @@ class FormItem extends ThemableMixin(PolymerElement) {
           min-width: 0;
         }
       </style>
-      <div id="label" part="label" on-click="_onLabelClick">
-        <slot name="label" id="labelSlot"></slot>
+      <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>
       </div>
       <div id="spacing"></div>
       <div id="content">
-        <slot id="contentSlot"></slot>
+        <slot id="contentSlot" on-slotchange="__onContentSlotChange"></slot>
       </div>
     `;
   }
@@ -159,17 +148,181 @@ class FormItem extends ThemableMixin(PolymerElement) {
     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;
+
+    // Ensure every instance has unique ID
+    const uniqueId = (FormItem._uniqueLabelId = 1 + FormItem._uniqueLabelId || 0);
+    this.__labelId = `label-${this.localName}-${uniqueId}`;
+  }
+
+  /**
+   * 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 firstContentElementChild = Array.prototype.find.call(
-      this.$.contentSlot.assignedNodes(),
-      (e) => e.nodeType === Node.ELEMENT_NODE
-    );
-    if (firstContentElementChild) {
-      firstContentElementChild.focus();
-      firstContentElementChild.click();
+  __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.id = '';
+      this.__labelNode = null;
+
+      if (this.__fieldNode) {
+        this.__unlinkLabelFromField(this.__fieldNode);
+      }
+    }
+
+    const newLabelNode = this.$.labelSlot.assignedElements()[0];
+    if (newLabelNode) {
+      this.__labelNode = newLabelNode;
+      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);
+  }
 }
 
 customElements.define(FormItem.is, FormItem);

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

@@ -1,9 +1,10 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2017 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
+import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 export type FormLayoutLabelsPosition = 'aside' | 'top';
@@ -104,7 +105,7 @@ export type FormLayoutResponsiveStep = {
  * ---|---|---
  * `--vaadin-form-layout-column-spacing` | Length of the spacing between columns | `2em`
  */
-declare class FormLayout extends ElementMixin(ThemableMixin(HTMLElement)) {
+declare class FormLayout extends ResizeMixin(ElementMixin(ThemableMixin(HTMLElement))) {
   /**
    * Allows specifying a responsive behavior with the number of columns
    * and the label position depending on the layout width.
@@ -146,8 +147,16 @@ declare class FormLayout extends ElementMixin(ThemableMixin(HTMLElement)) {
 
   /**
    * Set custom CSS property values and update the layout.
+   *
+   * @deprecated Since Vaadin 23, `updateStyles()` is deprecated.
+   * Use the native element.style.setProperty API to set custom CSS property values.
    */
   updateStyles(properties?: { [key: string]: string }): void;
+
+  /**
+   * Update the layout.
+   */
+  protected _updateLayout(): void;
 }
 
 declare global {

package/src/vaadin-form-layout.js

@@ -1,14 +1,12 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2017 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { IronResizableBehavior } from '@polymer/iron-resizable-behavior/iron-resizable-behavior.js';
-import { mixinBehaviors } from '@polymer/polymer/lib/legacy/class.js';
 import { FlattenedNodesObserver } from '@polymer/polymer/lib/utils/flattened-nodes-observer.js';
-import { beforeNextRender } from '@polymer/polymer/lib/utils/render-status.js';
 import { html, PolymerElement } from '@polymer/polymer/polymer-element.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
+import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 /**
@@ -104,8 +102,9 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  * @extends HTMLElement
  * @mixes ElementMixin
  * @mixes ThemableMixin
+ * @mixes ResizeMixin
  */
-class FormLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizableBehavior], PolymerElement))) {
+class FormLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolymerElement))) {
   static get template() {
     return html`
       <style>
@@ -243,7 +242,7 @@ class FormLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizabl
   }
 
   static get observers() {
-    return ['_invokeUpdateStyles(_columnCount, _labelsOnTop)'];
+    return ['_invokeUpdateLayout(_columnCount, _labelsOnTop)'];
   }
 
   /** @protected */
@@ -254,13 +253,12 @@ class FormLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizabl
     // `super.ready()`, because `super.ready()` invokes property observers,
     // and the observer for `responsiveSteps` does CSS value validation.
     this._styleElement = document.createElement('style');
-    this.root.appendChild(this._styleElement);
+    this.appendChild(this._styleElement);
     // Ensure there is a child text node in the style element
     this._styleElement.textContent = ' ';
 
     super.ready();
 
-    this.addEventListener('iron-resize', this._selectResponsiveStep);
     this.addEventListener('animationend', this.__onAnimationEnd);
   }
 
@@ -268,8 +266,8 @@ class FormLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizabl
   connectedCallback() {
     super.connectedCallback();
 
-    beforeNextRender(this, this._selectResponsiveStep);
-    beforeNextRender(this, this.updateStyles);
+    requestAnimationFrame(() => this._selectResponsiveStep());
+    requestAnimationFrame(() => this._updateLayout());
 
     this._observeChildrenColspanChange();
   }
@@ -293,7 +291,7 @@ class FormLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizabl
           mutation.type === 'attributes' &&
           (mutation.attributeName === 'colspan' || mutation.attributeName === 'hidden')
         ) {
-          this.updateStyles();
+          this._updateLayout();
         }
       });
     });
@@ -307,7 +305,7 @@ class FormLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizabl
       });
 
       if (addedNodes.length > 0 || removedNodes.length > 0) {
-        this.updateStyles();
+        this._updateLayout();
       }
     });
   }
@@ -433,18 +431,33 @@ class FormLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizabl
   }
 
   /** @private */
-  _invokeUpdateStyles() {
-    this.updateStyles();
+  _invokeUpdateLayout() {
+    this._updateLayout();
   }
 
   /**
    * Set custom CSS property values and update the layout.
-   * @param {Object<string, string>=} properties
-   * @protected
+   *
+   * @deprecated Since Vaadin 23, `updateStyles()` is deprecated.
+   * Use the native element.style.setProperty API to set custom CSS property values.
    */
-  updateStyles(properties) {
-    super.updateStyles(properties);
+  updateStyles(properties = {}) {
+    console.warn(
+      `WARNING: Since Vaadin 23, updateStyles() is deprecated. Use the native element.style.setProperty API to set custom CSS property values.`
+    );
+
+    Object.entries(properties).forEach(([key, value]) => {
+      this.style.setProperty(key, value);
+    });
 
+    this._updateLayout();
+  }
+
+  /**
+   * Update the layout.
+   * @protected
+   */
+  _updateLayout() {
     /*
       The item width formula:
 
@@ -525,6 +538,14 @@ class FormLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizabl
         }
       });
   }
+
+  /**
+   * @protected
+   * @override
+   */
+  _onResize() {
+    this._selectResponsiveStep();
+  }
 }
 
 customElements.define(FormLayout.is, FormLayout);

package/theme/lumo/vaadin-form-item-styles.js

@@ -23,6 +23,24 @@ registerStyles(
       transition: color 0.4s;
       line-height: 1.333;
     }
+
+    [part='required-indicator']::after {
+      content: var(--lumo-required-field-indicator, '•');
+      transition: opacity 0.2s;
+      opacity: 0;
+      color: var(--lumo-required-field-indicator-color, var(--lumo-primary-text-color));
+      position: relative;
+      width: 1em;
+      text-align: center;
+    }
+
+    :host([required]) [part='required-indicator']::after {
+      opacity: 1;
+    }
+
+    :host([invalid]) [part='required-indicator']::after {
+      color: var(--lumo-required-field-indicator-color, var(--lumo-error-text-color));
+    }
   `,
   { moduleId: 'lumo-form-item' }
 );

package/theme/material/vaadin-form-item-styles.js

@@ -14,6 +14,15 @@ registerStyles(
       margin-top: 16px;
       margin-bottom: 8px;
     }
+
+    :host([required]) [part='required-indicator']::after {
+      content: ' *';
+      color: inherit;
+    }
+
+    :host([invalid]) [part='label'] {
+      color: var(--material-error-text-color);
+    }
   `,
   { moduleId: 'material-form-item' }
 );