@vaadin/a11y-base 25.3.0-alpha7 → 25.3.0-alpha9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/a11y-base",
-  "version": "25.3.0-alpha7",
+  "version": "25.3.0-alpha9",
   "publishConfig": {
     "access": "public"
   },
@@ -32,15 +32,15 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/component-base": "25.3.0-alpha7",
+    "@vaadin/component-base": "25.3.0-alpha9",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "25.3.0-alpha7",
-    "@vaadin/test-runner-commands": "25.3.0-alpha7",
+    "@vaadin/chai-plugins": "25.3.0-alpha9",
+    "@vaadin/test-runner-commands": "25.3.0-alpha9",
     "@vaadin/testing-helpers": "^2.0.0",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
-  "gitHead": "ae7b9823df5598faebd7a482993029ee489c35ae"
+  "gitHead": "cb915ebde095ec5b94a87af93dd4530f51984c52"
 }

package/src/aria-element-reference.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright (c) 2000 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * Adds the element to the target's `ariaDescribedByElements` or
+ * `ariaLabelledByElements` property, based on the given attribute.
+ * Unlike ID references, element references also work across shadow roots.
+ */
+export function addAriaElementReference(
+  target: HTMLElement,
+  attr: 'aria-describedby' | 'aria-labelledby',
+  element: HTMLElement,
+): void;
+
+/**
+ * Removes the element from the target's `ariaDescribedByElements` or
+ * `ariaLabelledByElements` property, based on the given attribute.
+ * When the last element is removed, the property is reset to `null`
+ * so it no longer overrides the content attribute.
+ */
+export function removeAriaElementReference(
+  target: HTMLElement,
+  attr: 'aria-describedby' | 'aria-labelledby',
+  element: HTMLElement,
+): void;

package/src/aria-element-reference.js

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright (c) 2000 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+const ARIA_REFERENCE_PROPERTIES = {
+  'aria-describedby': 'ariaDescribedByElements',
+  'aria-labelledby': 'ariaLabelledByElements',
+};
+
+/**
+ * Adds the element to the target's `ariaDescribedByElements` or
+ * `ariaLabelledByElements` property, based on the given attribute.
+ * Unlike ID references, element references also work across shadow roots.
+ *
+ * @param {HTMLElement} target
+ * @param {'aria-describedby' | 'aria-labelledby'} attr
+ * @param {HTMLElement} element
+ */
+export function addAriaElementReference(target, attr, element) {
+  const property = ARIA_REFERENCE_PROPERTIES[attr];
+  const elements = new Set(target[property]);
+  elements.add(element);
+  target[property] = [...elements];
+}
+
+/**
+ * Removes the element from the target's `ariaDescribedByElements` or
+ * `ariaLabelledByElements` property, based on the given attribute.
+ * When the last element is removed, the property is reset to `null`
+ * so it no longer overrides the content attribute.
+ *
+ * @param {HTMLElement} target
+ * @param {'aria-describedby' | 'aria-labelledby'} attr
+ * @param {HTMLElement} element
+ */
+export function removeAriaElementReference(target, attr, element) {
+  const property = ARIA_REFERENCE_PROPERTIES[attr];
+  const elements = new Set(target[property]);
+  elements.delete(element);
+  target[property] = elements.size > 0 ? [...elements] : null;
+}

package/src/disabled-mixin.js

@@ -4,6 +4,7 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { dedupeMixin } from '@open-wc/dedupe-mixin';
+import { setOrRemoveAttribute } from '@vaadin/component-base/src/dom-utils.js';
 
 /**
  * A mixin to provide disabled property for field components.
@@ -38,11 +39,7 @@ const DisabledMixinImplementation = (superclass) => {
      * @protected
      */
     _setAriaDisabled(disabled) {
-      if (disabled) {
-        this.setAttribute('aria-disabled', 'true');
-      } else {
-        this.removeAttribute('aria-disabled');
-      }
+      setOrRemoveAttribute(this, 'aria-disabled', disabled);
     }
 
     /**

package/src/field-aria-controller.d.ts

@@ -33,31 +33,34 @@ export class FieldAriaController {
    *
    * To remove the attribute, pass `null` as `label`.
    */
-  setAriaLabel(label: string | null): void;
+  setLabel(label: string | null): void;
 
   /**
-   * Links the target element with a slotted label element
-   * via the target's attribute `aria-labelledby`.
+   * Links the target element to one or more elements via the `aria-labelledby` attribute.
    *
-   * To unlink the previous slotted label element, pass `null` as `labelId`.
+   * Pass a space-delimited list of IDs, or `null` to remove the previously linked IDs.
    */
-  setLabelId(labelId: string | null, fromUser: boolean | null): void;
+  setLabelledBy(labelledBy: string | null): void;
 
   /**
-   * Links the target element with a slotted error element via the target's attribute:
-   * - `aria-labelledby` if the target is the host component (e.g a field group).
-   * - `aria-describedby` otherwise.
+   * Links the target element to one or more elements via the `aria-describedby` attribute.
    *
-   * To unlink the previous slotted error element, pass `null` as `errorId`.
+   * @param describedBy the space-delimited list of IDs,
+   * or `null` to remove the previously linked IDs
+   */
+  setDescribedBy(describedBy: string | null): void;
+
+  /**
+   * Links the target element to a slotted error element via the `aria-describedby` attribute.
+   *
+   * Pass the ID of the error element, or `null` to remove the previously linked ID.
    */
   setErrorId(errorId: string | null): void;
 
   /**
-   * Links the target element with a slotted helper element via the target's attribute:
-   * - `aria-labelledby` if the target is the host component (e.g a field group).
-   * - `aria-describedby` otherwise.
+   * Links the target element to a slotted helper element via the `aria-describedby` attribute.
    *
-   * To unlink the previous slotted helper element, pass `null` as `helperId`.
+   * Pass the ID of the helper element, or `null` to remove the previously linked ID.
    */
   setHelperId(helperId: string | null): void;
 }

package/src/field-aria-controller.js

@@ -3,7 +3,11 @@
  * Copyright (c) 2021 - 2026 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { removeAriaIDReference, restoreGeneratedAriaIDReference, setAriaIDReference } from './aria-id-reference.js';
+import {
+  addValuesToAttribute,
+  removeValuesFromAttribute,
+  setOrRemoveAttribute,
+} from '@vaadin/component-base/src/dom-utils.js';
 
 /**
  * A controller for managing ARIA attributes for a field element:
@@ -20,10 +24,10 @@ export class FieldAriaController {
   #label;
 
   /** @type {string | null | undefined} */
-  #labelId;
+  #labelledBy;
 
   /** @type {string | null | undefined} */
-  #labelIdFromUser;
+  #describedBy;
 
   /** @type {string | null | undefined} */
   #errorId;
@@ -31,6 +35,12 @@ export class FieldAriaController {
   /** @type {string | null | undefined} */
   #helperId;
 
+  /** @type {string[]} */
+  #ariaLabelledByAttributeIds = [];
+
+  /** @type {string[]} */
+  #ariaDescribedByAttributeIds = [];
+
   constructor(host) {
     this.host = host;
   }
@@ -42,15 +52,10 @@ export class FieldAriaController {
    */
   setTarget(target) {
     this.#target = target;
-    this.#setAriaRequiredAttribute(this.#required);
-    // We need to make sure that value in #labelId is stored
-    this.#setLabelIdToAriaAttribute(this.#labelId, this.#labelId);
-    if (this.#labelIdFromUser != null) {
-      this.#setLabelIdToAriaAttribute(this.#labelIdFromUser, this.#labelIdFromUser, true);
-    }
-    this.#setErrorIdToAriaAttribute(this.#errorId);
-    this.#setHelperIdToAriaAttribute(this.#helperId);
-    this.setAriaLabel(this.#label);
+    this.#updateAriaLabelAttribute();
+    this.#updateAriaLabelledByAttribute();
+    this.#updateAriaDescribedByAttribute();
+    this.#updateAriaRequiredAttribute();
   }
 
   /**
@@ -61,8 +66,8 @@ export class FieldAriaController {
    * @param {boolean} required
    */
   setRequired(required) {
-    this.#setAriaRequiredAttribute(required);
     this.#required = required;
+    this.#updateAriaRequiredAttribute();
   }
 
   /**
@@ -72,102 +77,88 @@ export class FieldAriaController {
    *
    * @param {string | null | undefined} label
    */
-  setAriaLabel(label) {
-    this.#setAriaLabelToAttribute(label);
+  setLabel(label) {
     this.#label = label;
+    this.#updateAriaLabelAttribute();
   }
 
   /**
-   * Links the target element with a slotted label element
-   * via the target's attribute `aria-labelledby`.
+   * Links the target element to one or more elements via the `aria-labelledby` attribute.
    *
-   * To unlink the previous slotted label element, pass `null` as `labelId`.
-   *
-   * @param {string | null} labelId
+   * @param {string | null} labelledBy the space-delimited list of IDs,
+   * or `null` to remove the previously linked IDs
    */
-  setLabelId(labelId, fromUser = false) {
-    const oldLabelId = fromUser ? this.#labelIdFromUser : this.#labelId;
-    this.#setLabelIdToAriaAttribute(labelId, oldLabelId, fromUser);
-    if (fromUser) {
-      this.#labelIdFromUser = labelId;
-    } else {
-      this.#labelId = labelId;
-    }
+  setLabelledBy(labelledBy) {
+    this.#labelledBy = labelledBy;
+    this.#updateAriaLabelledByAttribute();
   }
 
   /**
-   * Links the target element with a slotted error element via the target's attribute:
-   * - `aria-labelledby` if the target is the host component (e.g a field group).
-   * - `aria-describedby` otherwise.
+   * Links the target element to one or more elements via the `aria-describedby` attribute.
    *
-   * To unlink the previous slotted error element, pass `null` as `errorId`.
+   * @param {string | null} describedBy the space-delimited list of IDs,
+   * or `null` to remove the previously linked IDs
+   */
+  setDescribedBy(describedBy) {
+    this.#describedBy = describedBy;
+    this.#updateAriaDescribedByAttribute();
+  }
+
+  /**
+   * Links the target element to a slotted error element via the `aria-describedby` attribute.
    *
-   * @param {string | null} errorId
+   * @param {string | null} errorId the ID of the error element,
+   * or `null` to remove the previously linked ID
    */
   setErrorId(errorId) {
-    this.#setErrorIdToAriaAttribute(errorId, this.#errorId);
     this.#errorId = errorId;
+    this.#updateAriaDescribedByAttribute();
   }
 
   /**
-   * Links the target element with a slotted helper element via the target's attribute:
-   * - `aria-labelledby` if the target is the host component (e.g a field group).
-   * - `aria-describedby` otherwise.
-   *
-   * To unlink the previous slotted helper element, pass `null` as `helperId`.
+   * Links the target element to a slotted helper element via the `aria-describedby` attribute.
    *
-   * @param {string | null} helperId
+   * @param {string | null} helperId the ID of the helper element,
+   * or `null` to remove the previously linked ID
    */
   setHelperId(helperId) {
-    this.#setHelperIdToAriaAttribute(helperId, this.#helperId);
     this.#helperId = helperId;
+    this.#updateAriaDescribedByAttribute();
   }
 
-  /**
-   * @param {string | null | undefined} label
-   */
-  #setAriaLabelToAttribute(label) {
+  #updateAriaLabelAttribute() {
     if (!this.#target) {
       return;
     }
-    if (label) {
-      removeAriaIDReference(this.#target, 'aria-labelledby');
-      this.#target.setAttribute('aria-label', label);
-    } else if (this.#label) {
-      restoreGeneratedAriaIDReference(this.#target, 'aria-labelledby');
-      this.#target.removeAttribute('aria-label');
-    }
-  }
 
-  /**
-   * @param {string | null | undefined} labelId
-   * @param {string | null | undefined} oldLabelId
-   * @param {boolean | null | undefined} fromUser
-   */
-  #setLabelIdToAriaAttribute(labelId, oldLabelId, fromUser) {
-    setAriaIDReference(this.#target, 'aria-labelledby', { newId: labelId, oldId: oldLabelId, fromUser });
+    setOrRemoveAttribute(this.#target, 'aria-label', this.#label);
   }
 
-  /**
-   * @param {string | null | undefined} errorId
-   * @param {string | null | undefined} oldErrorId
-   */
-  #setErrorIdToAriaAttribute(errorId, oldErrorId) {
-    setAriaIDReference(this.#target, 'aria-describedby', { newId: errorId, oldId: oldErrorId, fromUser: false });
+  #updateAriaLabelledByAttribute() {
+    if (!this.#target) {
+      return;
+    }
+
+    removeValuesFromAttribute(this.#target, 'aria-labelledby', this.#ariaLabelledByAttributeIds);
+
+    this.#ariaLabelledByAttributeIds = [this.#labelledBy];
+
+    addValuesToAttribute(this.#target, 'aria-labelledby', this.#ariaLabelledByAttributeIds);
   }
 
-  /**
-   * @param {string | null | undefined} helperId
-   * @param {string | null | undefined} oldHelperId
-   */
-  #setHelperIdToAriaAttribute(helperId, oldHelperId) {
-    setAriaIDReference(this.#target, 'aria-describedby', { newId: helperId, oldId: oldHelperId, fromUser: false });
+  #updateAriaDescribedByAttribute() {
+    if (!this.#target) {
+      return;
+    }
+
+    removeValuesFromAttribute(this.#target, 'aria-describedby', this.#ariaDescribedByAttributeIds);
+
+    this.#ariaDescribedByAttributeIds = [this.#describedBy, this.#helperId, this.#errorId];
+
+    addValuesToAttribute(this.#target, 'aria-describedby', this.#ariaDescribedByAttributeIds);
   }
 
-  /**
-   * @param {boolean} required
-   */
-  #setAriaRequiredAttribute(required) {
+  #updateAriaRequiredAttribute() {
     if (!this.#target) {
       return;
     }
@@ -177,10 +168,6 @@ export class FieldAriaController {
       return;
     }
 
-    if (required) {
-      this.#target.setAttribute('aria-required', 'true');
-    } else {
-      this.#target.removeAttribute('aria-required');
-    }
+    setOrRemoveAttribute(this.#target, 'aria-required', this.#required);
   }
 }

package/src/list-mixin.js

@@ -6,6 +6,7 @@
 import { timeOut } from '@vaadin/component-base/src/async.js';
 import { Debouncer } from '@vaadin/component-base/src/debounce.js';
 import { getNormalizedScrollLeft, setNormalizedScrollLeft } from '@vaadin/component-base/src/dir-utils.js';
+import { setOrRemoveAttribute } from '@vaadin/component-base/src/dom-utils.js';
 import { SlotObserver } from '@vaadin/component-base/src/slot-observer.js';
 import { isElementHidden } from './focus-utils.js';
 import { KeyboardDirectionMixin } from './keyboard-direction-mixin.js';
@@ -163,13 +164,7 @@ export const ListMixin = (superClass) =>
       if (!disabled) {
         if (items) {
           this.setAttribute('aria-orientation', orientation || 'vertical');
-          items.forEach((item) => {
-            if (orientation) {
-              item.setAttribute('orientation', orientation);
-            } else {
-              item.removeAttribute('orientation');
-            }
-          });
+          items.forEach((item) => setOrRemoveAttribute(item, 'orientation', orientation));
 
           // When selected is set to -1, focus the first available item.
           this._setFocusable(selected < 0 || !selected ? 0 : selected);

package/src/aria-id-reference.d.ts

@@ -1,41 +0,0 @@
-/**
- * @license
- * Copyright (c) 2023 - 2026 Vaadin Ltd.
- * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
- */
-
-export type AriaIDReferenceConfig = {
-  newId: string | null;
-  oldId: string | null;
-  fromUser: boolean | null;
-};
-
-/**
- * Sets a new ID reference for a target element and an ARIA attribute.
- *
- * @param config.newId
- *  The new ARIA ID reference to set. If `null`, the attribute is removed,
- *  and `config.fromUser` is `true`, any stored values are restored. If there
- *  are stored values and `config.fromUser` is `false`, then `config.newId`
- *  is added to the stored values set.
- * @param config.oldId
- *  The ARIA ID reference to be removed from the attribute. If there are stored
- *  values and `config.fromUser` is `false`, then `config.oldId` is removed from
- *  the stored values set.
- * @param config.fromUser
- *  Indicates whether the function is called by the user or internally.
- *  When `config.fromUser` is called with `true` for the first time,
- *  the function will clear and store the attribute value for the given element.
- */
-export function setAriaIDReference(target: HTMLElement, attr: string, config: AriaIDReferenceConfig): void;
-
-/**
- * Removes the attribute value of the given target element.
- * It also stores the current value, if no stored values are present.
- */
-export function removeAriaIDReference(target: HTMLElement, attr: string): void;
-
-/**
- * Restores the generated values of the attribute to the given target element.
- */
-export function restoreGeneratedAriaIDReference(target: HTMLElement, attr: string): void;

package/src/aria-id-reference.js

@@ -1,154 +0,0 @@
-/**
- * @license
- * Copyright (c) 2023 - 2026 Vaadin Ltd.
- * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
- */
-import {
-  addValueToAttribute,
-  deserializeAttributeValue,
-  removeValueFromAttribute,
-  serializeAttributeValue,
-} from '@vaadin/component-base/src/dom-utils.js';
-
-const attributeToTargets = new Map();
-
-/**
- * Gets or creates a Set with the stored values for each element controlled by this helper
- *
- * @param {string} attr the attribute name used as key in the map
- *
- * @return {WeakMap<HTMLElement, Set<string>>} a weak map with the stored values for the elements being controlled by the helper
- */
-function getAttrMap(attr) {
-  if (!attributeToTargets.has(attr)) {
-    attributeToTargets.set(attr, new WeakMap());
-  }
-  return attributeToTargets.get(attr);
-}
-
-/**
- * Cleans the values set on the attribute to the given element.
- * It also stores the current values in the map, if `storeValue` is `true`.
- *
- * @param {HTMLElement} target
- * @param {string} attr the attribute to be cleared
- */
-function cleanAriaIDReference(target, attr) {
-  if (!target) {
-    return;
-  }
-
-  target.removeAttribute(attr);
-}
-
-/**
- * Storing values of the accessible attributes in a Set inside of the WeakMap.
- *
- * @param {HTMLElement} target
- * @param {string} attr the attribute to be stored
- */
-function storeAriaIDReference(target, attr) {
-  if (!target || !attr) {
-    return;
-  }
-  const attributeMap = getAttrMap(attr);
-  if (attributeMap.has(target)) {
-    return;
-  }
-  const values = deserializeAttributeValue(target.getAttribute(attr));
-  attributeMap.set(target, new Set(values));
-}
-
-/**
- * Restores the generated values of the attribute to the given element.
- *
- * @param {HTMLElement} target
- * @param {string} attr
- */
-export function restoreGeneratedAriaIDReference(target, attr) {
-  if (!target || !attr) {
-    return;
-  }
-  const attributeMap = getAttrMap(attr);
-  const values = attributeMap.get(target);
-  if (!values || values.size === 0) {
-    target.removeAttribute(attr);
-  } else {
-    addValueToAttribute(target, attr, serializeAttributeValue(values));
-  }
-  attributeMap.delete(target);
-}
-
-/**
- * Sets a new ID reference for a target element and an ARIA attribute.
- *
- * @typedef {Object} AriaIdReferenceConfig
- * @property {string | null | undefined} newId
- * @property {string | null | undefined} oldId
- * @property {boolean | null | undefined} fromUser
- * @param {HTMLElement} target
- * @param {string} attr
- * @param {AriaIdReferenceConfig | null | undefined} config
- * @param config.newId The new ARIA ID reference to set. If `null`, the attribute is removed,
- * and `config.fromUser` is true, any stored values are restored. If there are stored values
- * and `config.fromUser` is `false`, then `config.newId` is added to the stored values set.
- * @param config.oldId The ARIA ID reference to be removed from the attribute. If there are
- * stored values and `config.fromUser` is `false`, then `config.oldId` is removed from the
- * stored values set.
- * @param config.fromUser Indicates whether the function is called by the user or internally.
- * When `config.fromUser` is called with `true` for the first time, the function will clear
- * and store the attribute value for the given element.
- */
-export function setAriaIDReference(target, attr, config = { newId: null, oldId: null, fromUser: false }) {
-  if (!target || !attr) {
-    return;
-  }
-
-  const { newId, oldId, fromUser } = config;
-
-  const attributeMap = getAttrMap(attr);
-  const storedValues = attributeMap.get(target);
-
-  if (!fromUser && !!storedValues) {
-    // If there's any stored values, it means the attribute is being handled by the user
-    // Replace the "oldId" with "newId" on the stored values set and leave
-    oldId && storedValues.delete(oldId);
-    newId && storedValues.add(newId);
-    return;
-  }
-
-  if (fromUser) {
-    if (!storedValues) {
-      // If it's called from user and there's no stored values for the attribute,
-      // then store the current value
-      storeAriaIDReference(target, attr);
-    } else if (!newId) {
-      // If called from user with newId == null, it means the attribute will no longer
-      // be in control of the user and the stored values should be restored
-      // Removing the entry on the map for this target
-      attributeMap.delete(target);
-    }
-
-    // If it's from user, then clear the attribute value before setting newId
-    cleanAriaIDReference(target, attr);
-  }
-
-  removeValueFromAttribute(target, attr, oldId);
-
-  const attributeValue = !newId ? serializeAttributeValue(storedValues) : newId;
-  if (attributeValue) {
-    addValueToAttribute(target, attr, attributeValue);
-  }
-}
-
-/**
- * Removes the {@link attr | attribute} value of the given {@link target} element.
- * It also stores the current value, if no stored values are present.
- *
- * @param {HTMLElement} target
- * @param {string} attr
- */
-export function removeAriaIDReference(target, attr) {
-  storeAriaIDReference(target, attr);
-  cleanAriaIDReference(target, attr);
-}