@vaadin/field-base 25.2.7 → 25.3.0-alpha10

package/custom-elements.json

@@ -227,6 +227,16 @@
           "description": "A mixin to provide common field logic: label, error message and helper text.",
           "name": "FieldMixin",
           "members": [
+            {
+              "kind": "field",
+              "name": "accessibleDescriptionRef",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "A space-separated list of IDs referencing the elements that\ndescribe the component for screen reader users. The referenced\nelements are announced in addition to the helper text and\nthe error message.",
+              "attribute": "accessible-description-ref"
+            },
             {
               "kind": "field",
               "name": "accessibleName",
@@ -234,7 +244,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "attribute": "accessible-name"
             },
             {
@@ -244,7 +254,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "attribute": "accessible-name-ref"
             },
             {
@@ -353,12 +363,20 @@
             }
           ],
           "attributes": [
+            {
+              "name": "accessible-description-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "A space-separated list of IDs referencing the elements that\ndescribe the component for screen reader users. The referenced\nelements are announced in addition to the helper text and\nthe error message.",
+              "fieldName": "accessibleDescriptionRef"
+            },
             {
               "name": "accessible-name",
               "type": {
                 "text": "string"
               },
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "fieldName": "accessibleName"
             },
             {
@@ -366,7 +384,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "fieldName": "accessibleNameRef"
             },
             {
@@ -690,6 +708,20 @@
           "description": "A mixin to provide shared logic for the editable form input controls.",
           "name": "InputControlMixin",
           "members": [
+            {
+              "kind": "field",
+              "name": "accessibleDescriptionRef",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "A space-separated list of IDs referencing the elements that\ndescribe the component for screen reader users. The referenced\nelements are announced in addition to the helper text and\nthe error message.",
+              "attribute": "accessible-description-ref",
+              "inheritedFrom": {
+                "name": "FieldMixin",
+                "module": "src/field-mixin.js"
+              }
+            },
             {
               "kind": "field",
               "name": "accessibleName",
@@ -697,7 +729,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "attribute": "accessible-name",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -711,7 +743,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "attribute": "accessible-name-ref",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -957,12 +989,24 @@
             }
           ],
           "attributes": [
+            {
+              "name": "accessible-description-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "A space-separated list of IDs referencing the elements that\ndescribe the component for screen reader users. The referenced\nelements are announced in addition to the helper text and\nthe error message.",
+              "fieldName": "accessibleDescriptionRef",
+              "inheritedFrom": {
+                "name": "FieldMixin",
+                "module": "src/field-mixin.js"
+              }
+            },
             {
               "name": "accessible-name",
               "type": {
                 "text": "string"
               },
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "fieldName": "accessibleName",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -974,7 +1018,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "fieldName": "accessibleNameRef",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -1225,6 +1269,20 @@
           "description": "A mixin to provide logic for vaadin-text-field and related components.",
           "name": "InputFieldMixin",
           "members": [
+            {
+              "kind": "field",
+              "name": "accessibleDescriptionRef",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "A space-separated list of IDs referencing the elements that\ndescribe the component for screen reader users. The referenced\nelements are announced in addition to the helper text and\nthe error message.",
+              "attribute": "accessible-description-ref",
+              "inheritedFrom": {
+                "name": "FieldMixin",
+                "module": "src/field-mixin.js"
+              }
+            },
             {
               "kind": "field",
               "name": "accessibleName",
@@ -1232,7 +1290,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "attribute": "accessible-name",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -1246,7 +1304,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "attribute": "accessible-name-ref",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -1546,12 +1604,24 @@
             }
           ],
           "attributes": [
+            {
+              "name": "accessible-description-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "A space-separated list of IDs referencing the elements that\ndescribe the component for screen reader users. The referenced\nelements are announced in addition to the helper text and\nthe error message.",
+              "fieldName": "accessibleDescriptionRef",
+              "inheritedFrom": {
+                "name": "FieldMixin",
+                "module": "src/field-mixin.js"
+              }
+            },
             {
               "name": "accessible-name",
               "type": {
                 "text": "string"
               },
-              "description": "String used to label the component to screen reader users.",
+              "description": "String used to label the component for screen reader users.",
               "fieldName": "accessibleName",
               "inheritedFrom": {
                 "name": "FieldMixin",
@@ -1563,7 +1633,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Id of the element used as label of the component to screen reader users.",
+              "description": "A space-separated list of IDs referencing the elements that\nlabel the component for screen reader users.",
               "fieldName": "accessibleNameRef",
               "inheritedFrom": {
                 "name": "FieldMixin",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/field-base",
-  "version": "25.2.7",
+  "version": "25.3.0-alpha10",
   "publishConfig": {
     "access": "public"
   },
@@ -32,17 +32,17 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "~25.2.7",
-    "@vaadin/component-base": "~25.2.7",
+    "@vaadin/a11y-base": "25.3.0-alpha10",
+    "@vaadin/component-base": "25.3.0-alpha10",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "~25.2.7",
-    "@vaadin/input-container": "~25.2.7",
-    "@vaadin/test-runner-commands": "~25.2.7",
+    "@vaadin/chai-plugins": "25.3.0-alpha10",
+    "@vaadin/input-container": "25.3.0-alpha10",
+    "@vaadin/test-runner-commands": "25.3.0-alpha10",
     "@vaadin/testing-helpers": "^2.0.0",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
-  "gitHead": "14be1af674f3968cce68c6eb4742340694c4a949"
+  "gitHead": "f2833abdf9b613fa0d0ed216830e3f4de87b7dac"
 }

package/src/field-mixin.d.ts

@@ -30,17 +30,30 @@ export declare class FieldMixinClass {
   errorMessage: string | null | undefined;
 
   /**
-   * String used to label the component to screen reader users.
+   * String used to label the component for screen reader users.
+   *
    * @attr {string} accessible-name
    */
   accessibleName: string | null | undefined;
 
   /**
-   * Id of the element used as label of the component to screen reader users.
+   * A space-separated list of IDs referencing the elements that
+   * label the component for screen reader users.
+   *
    * @attr {string} accessible-name-ref
    */
   accessibleNameRef: string | null | undefined;
 
+  /**
+   * A space-separated list of IDs referencing the elements that
+   * describe the component for screen reader users. The referenced
+   * elements are announced in addition to the helper text and
+   * the error message.
+   *
+   * @attr {string} accessible-description-ref
+   */
+  accessibleDescriptionRef: string | null | undefined;
+
   /**
    * A target element to which ARIA attributes are set.
    */
@@ -49,12 +62,4 @@ export declare class FieldMixinClass {
   protected readonly _errorNode: HTMLElement;
 
   protected readonly _helperNode?: HTMLElement;
-
-  protected _helperTextChanged(helperText: string | null | undefined): void;
-
-  protected _ariaTargetChanged(target: HTMLElement): void;
-
-  protected _requiredChanged(required: boolean): void;
-
-  protected _invalidChanged(invalid: boolean): void;
 }

package/src/field-mixin.js

@@ -22,7 +22,6 @@ export const FieldMixin = (superclass) =>
          */
         ariaTarget: {
           type: Object,
-          observer: '_ariaTargetChanged',
         },
 
         /**
@@ -32,7 +31,6 @@ export const FieldMixin = (superclass) =>
          */
         errorMessage: {
           type: String,
-          observer: '_errorMessageChanged',
         },
 
         /**
@@ -41,54 +39,59 @@ export const FieldMixin = (superclass) =>
          */
         helperText: {
           type: String,
-          observer: '_helperTextChanged',
         },
 
         /**
-         * String used to label the component to screen reader users.
+         * String used to label the component for screen reader users.
+         *
          * @attr {string} accessible-name
          */
         accessibleName: {
           type: String,
-          observer: '_accessibleNameChanged',
         },
 
         /**
-         * Id of the element used as label of the component to screen reader users.
+         * A space-separated list of IDs referencing the elements that
+         * label the component for screen reader users.
+         *
          * @attr {string} accessible-name-ref
          */
         accessibleNameRef: {
           type: String,
-          observer: '_accessibleNameRefChanged',
         },
-      };
-    }
 
-    static get observers() {
-      return ['_invalidChanged(invalid)', '_requiredChanged(required)'];
+        /**
+         * A space-separated list of IDs referencing the elements that
+         * describe the component for screen reader users. The referenced
+         * elements are announced in addition to the helper text and
+         * the error message.
+         *
+         * @attr {string} accessible-description-ref
+         */
+        accessibleDescriptionRef: {
+          type: String,
+        },
+      };
     }
 
     constructor() {
       super();
 
-      this._fieldAriaController = new FieldAriaController(this);
-      this._helperController = new HelperController(this);
-      this._errorController = new ErrorController(this);
-
-      this._errorController.addEventListener('slot-content-changed', (event) => {
-        this.toggleAttribute('has-error-message', event.detail.hasContent);
-      });
-
       this._labelController.addEventListener('slot-content-changed', (event) => {
-        const { hasContent, node } = event.detail;
-        this.__labelChanged(hasContent, node);
+        this.#onLabelSlotContentChange(event);
       });
 
+      this._helperController = new HelperController(this);
       this._helperController.addEventListener('slot-content-changed', (event) => {
-        const { hasContent, node } = event.detail;
-        this.toggleAttribute('has-helper', hasContent);
-        this.__helperChanged(hasContent, node);
+        this.#onHelperSlotContentChange(event);
       });
+
+      this._errorController = new ErrorController(this);
+      this._errorController.addEventListener('slot-content-changed', (event) => {
+        this.#onErrorSlotContentChange(event);
+      });
+
+      this._fieldAriaController = new FieldAriaController(this);
     }
 
     /**
@@ -116,76 +119,86 @@ export const FieldMixin = (superclass) =>
       this.addController(this._errorController);
     }
 
-    /** @private */
-    __helperChanged(hasHelper, helperNode) {
-      if (hasHelper) {
-        this._fieldAriaController.setHelperId(helperNode.id);
-      } else {
-        this._fieldAriaController.setHelperId(null);
+    /** @protected */
+    updated(props) {
+      super.updated(props);
+
+      if (props.has('invalid')) {
+        this._errorController.setInvalid(this.invalid);
       }
-    }
 
-    /** @protected */
-    _accessibleNameChanged(accessibleName) {
-      this._fieldAriaController.setAriaLabel(accessibleName);
+      if (props.has('errorMessage')) {
+        this._errorController.setErrorMessage(this.errorMessage);
+      }
+
+      if (props.has('helperText')) {
+        this._helperController.setHelperText(this.helperText);
+      }
+
+      if (props.has('ariaTarget')) {
+        this._fieldAriaController.setTarget(this.ariaTarget);
+      }
+
+      if (props.has('required')) {
+        this._fieldAriaController.setRequired(this.required);
+      }
+
+      if (props.has('accessibleName')) {
+        this.__updateFieldAriaControllerLabel();
+      }
+
+      if (props.has('accessibleName') || props.has('accessibleNameRef')) {
+        this.__updateFieldAriaControllerLabelledBy();
+      }
+
+      if (props.has('accessibleDescriptionRef')) {
+        this.__updateFieldAriaControllerDescribedBy();
+      }
     }
 
-    /** @protected */
-    _accessibleNameRefChanged(accessibleNameRef) {
-      this._fieldAriaController.setLabelId(accessibleNameRef, true);
+    /** @private */
+    __updateFieldAriaControllerLabel() {
+      this._fieldAriaController.setLabel(this.accessibleName);
     }
 
     /** @private */
-    __labelChanged(hasLabel, labelNode) {
-      // Label ID should be only added when the label content is present.
-      // Otherwise, it may conflict with an `aria-label` attribute possibly added by the user.
-      if (hasLabel) {
-        this._fieldAriaController.setLabelId(labelNode.id);
-      } else {
-        this._fieldAriaController.setLabelId(null);
+    __updateFieldAriaControllerLabelledBy() {
+      let id = null;
+
+      if (this.accessibleNameRef) {
+        id = this.accessibleNameRef;
+      } else if (this.hasAttribute('has-label') && !this.accessibleName) {
+        // Label ID should be only added when the label content is present
+        // and not overridden by `accessible-name` which sets `aria-label`.
+        id = this._labelNode?.id;
       }
-    }
 
-    /**
-     * @param {string | null | undefined} errorMessage
-     * @protected
-     */
-    _errorMessageChanged(errorMessage) {
-      this._errorController.setErrorMessage(errorMessage);
+      this._fieldAriaController.setLabelledBy(id);
     }
 
-    /**
-     * @param {string} helperText
-     * @protected
-     */
-    _helperTextChanged(helperText) {
-      this._helperController.setHelperText(helperText);
+    /** @private */
+    __updateFieldAriaControllerDescribedBy() {
+      this._fieldAriaController.setDescribedBy(this.accessibleDescriptionRef);
     }
 
-    /**
-     * @param {HTMLElement | null | undefined} target
-     * @protected
-     */
-    _ariaTargetChanged(target) {
-      if (target) {
-        this._fieldAriaController.setTarget(target);
-      }
+    #onLabelSlotContentChange(_event) {
+      this.__updateFieldAriaControllerLabelledBy();
     }
 
-    /**
-     * @param {boolean} required
-     * @protected
-     */
-    _requiredChanged(required) {
-      this._fieldAriaController.setRequired(required);
+    #onHelperSlotContentChange(event) {
+      const { hasContent } = event.detail;
+
+      this.toggleAttribute('has-helper', hasContent);
+
+      if (hasContent) {
+        this._fieldAriaController.setHelperId(this._helperNode?.id);
+      } else {
+        this._fieldAriaController.setHelperId(null);
+      }
     }
 
-    /**
-     * @param {boolean} invalid
-     * @protected
-     */
-    _invalidChanged(invalid) {
-      this._errorController.setInvalid(invalid);
+    #onErrorSlotContentChange(event) {
+      this.toggleAttribute('has-error-message', event.detail.hasContent);
 
       // This timeout is needed to prevent NVDA from announcing the error message twice:
       // 1. Once adding the `[role=alert]` attribute when updating `has-error-message` (OK).
@@ -194,9 +207,8 @@ export const FieldMixin = (superclass) =>
       setTimeout(() => {
         // Error message ID needs to be dynamically added / removed based on the validity
         // Otherwise assistive technologies would announce the error, even if we hide it.
-        if (invalid) {
-          const node = this._errorNode;
-          this._fieldAriaController.setErrorId(node?.id);
+        if (this.invalid) {
+          this._fieldAriaController.setErrorId(this._errorNode?.id);
         } else {
           this._fieldAriaController.setErrorId(null);
         }

package/src/labelled-input-controller.js

@@ -10,23 +10,21 @@
 export class LabelledInputController {
   constructor(input, labelController) {
     this.input = input;
-    this.__preventDuplicateLabelClick = this.__preventDuplicateLabelClick.bind(this);
 
     labelController.addEventListener('slot-content-changed', (event) => {
-      this.__initLabel(event.detail.node);
+      this.#initLabel(event.detail.node);
     });
 
     // Initialize the default label element
-    this.__initLabel(labelController.node);
+    this.#initLabel(labelController.node);
   }
 
   /**
    * @param {HTMLElement} label
-   * @private
    */
-  __initLabel(label) {
+  #initLabel(label) {
     if (label) {
-      label.addEventListener('click', this.__preventDuplicateLabelClick);
+      label.addEventListener('click', this.#preventDuplicateLabelClick);
 
       if (this.input) {
         label.setAttribute('for', this.input.id);
@@ -40,13 +38,12 @@ export class LabelledInputController {
    * This results in two click events arriving at the host, but we only want one.
    * This method prevents the duplicate click and ensures the correct isTrusted event
    * with the correct event.target arrives at the host.
-   * @private
    */
-  __preventDuplicateLabelClick() {
+  #preventDuplicateLabelClick = () => {
     const inputClickHandler = (e) => {
       e.stopImmediatePropagation();
       this.input.removeEventListener('click', inputClickHandler);
     };
     this.input.addEventListener('click', inputClickHandler);
-  }
+  };
 }

package/src/styles/checkable-base-styles.js

@@ -18,10 +18,6 @@ export const checkable = (part, propName = part) => css`
     --_cursor: var(--vaadin-clickable-cursor);
   }
 
-  :host([disabled]) {
-    --_cursor: var(--vaadin-disabled-cursor);
-  }
-
   :host(:not([has-label])) {
     column-gap: 0;
   }
@@ -94,8 +90,8 @@ export const checkable = (part, propName = part) => css`
     box-sizing: border-box;
     --_color: var(--vaadin-${unsafeCSS(propName)}-marker-color, var(--vaadin-${unsafeCSS(propName)}-background, var(--vaadin-background-color)));
     color: var(--_color);
-    height: var(--vaadin-${unsafeCSS(propName)}-size, 1lh);
-    width: var(--vaadin-${unsafeCSS(propName)}-size, 1lh);
+    height: var(--vaadin-${unsafeCSS(propName)}-size, round(1.125em, 2px));
+    width: var(--vaadin-${unsafeCSS(propName)}-size, round(1.125em, 2px));
     position: relative;
     cursor: var(--_cursor);
     display: flex;
@@ -108,10 +104,24 @@ export const checkable = (part, propName = part) => css`
     --vaadin-${unsafeCSS(propName)}-border-color: transparent;
   }
 
+  :host([readonly]) {
+    --vaadin-${unsafeCSS(part)}-background: transparent;
+    --vaadin-${unsafeCSS(part)}-border-color: var(--vaadin-border-color);
+    --vaadin-${unsafeCSS(part)}-marker-color: var(--vaadin-text-color);
+    --_border-style: dashed;
+    --_cursor: var(--vaadin-disabled-cursor);
+
+    [part='label'],
+    ::slotted(label) {
+      cursor: default;
+    }
+  }
+
   :host([disabled]) {
     --vaadin-${unsafeCSS(propName)}-background: var(--vaadin-input-field-disabled-background, var(--vaadin-background-container-strong));
     --vaadin-${unsafeCSS(propName)}-border-color: transparent;
     --vaadin-${unsafeCSS(propName)}-marker-color: var(--vaadin-text-color-disabled);
+    --_cursor: var(--vaadin-disabled-cursor);
   }
 
   /* Focus ring */
@@ -145,6 +155,30 @@ export const checkable = (part, propName = part) => css`
     opacity: 0;
   }
 
+  /* Reverse variant */
+  :host([theme~='reverse']) {
+    grid-template-columns: 1fr auto;
+
+    &::before {
+      display: none;
+    }
+
+    [part='label'],
+    [part='helper-text'],
+    [part='error-message'] {
+      grid-column: 1;
+    }
+
+    [part='${unsafeCSS(part)}'],
+    ::slotted(input) {
+      grid-column: 2;
+    }
+
+    ::slotted(input) {
+      margin-inline: calc(min(0px, (24px - 100%) / -2) - var(--vaadin-${unsafeCSS(propName)}-gap, var(--vaadin-gap-s))) 0 !important;
+    }
+  }
+
   @media (forced-colors: active) {
     :host(:is([checked], [indeterminate])) {
       --vaadin-${unsafeCSS(propName)}-border-color: CanvasText !important;

package/src/virtual-keyboard-controller.js

@@ -18,19 +18,18 @@ export class VirtualKeyboardController {
     host.addEventListener('opened-changed', () => {
       if (!host.opened) {
         // Prevent opening the virtual keyboard when the input gets re-focused on dropdown close
-        this.__setVirtualKeyboardEnabled(false);
+        this.#setVirtualKeyboardEnabled(false);
       }
     });
 
     // Re-enable virtual keyboard on blur, so it gets opened when the field is focused again
-    host.addEventListener('blur', () => this.__setVirtualKeyboardEnabled(true));
+    host.addEventListener('blur', () => this.#setVirtualKeyboardEnabled(true));
 
     // Re-enable the virtual keyboard whenever the field is touched
-    host.addEventListener('touchstart', () => this.__setVirtualKeyboardEnabled(true));
+    host.addEventListener('touchstart', () => this.#setVirtualKeyboardEnabled(true));
   }
 
-  /** @private */
-  __setVirtualKeyboardEnabled(value) {
+  #setVirtualKeyboardEnabled(value) {
     if (this.host.inputElement) {
       this.host.inputElement.inputMode = value ? '' : 'none';
     }