@vaadin/a11y-base 25.2.7 → 25.3.0-alpha10

package/index.d.ts

@@ -5,7 +5,7 @@ export { DisabledMixin } from './src/disabled-mixin.js';
 export { FieldAriaController } from './src/field-aria-controller.js';
 export { FocusMixin } from './src/focus-mixin.js';
 export {
-  getFocusableElements,
+  getTabbableElements,
   isElementFocusable,
   isElementFocused,
   isElementHidden,

package/index.js

@@ -7,7 +7,7 @@ export { FocusMixin } from './src/focus-mixin.js';
 export { FocusTrapController } from './src/focus-trap-controller.js';
 export { FocusRestorationController } from './src/focus-restoration-controller.js';
 export {
-  getFocusableElements,
+  getTabbableElements,
   isElementFocusable,
   isElementFocused,
   isElementHidden,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/a11y-base",
-  "version": "25.2.7",
+  "version": "25.3.0-alpha10",
   "publishConfig": {
     "access": "public"
   },
@@ -32,15 +32,15 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/component-base": "~25.2.7",
+    "@vaadin/component-base": "25.3.0-alpha10",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "~25.2.7",
-    "@vaadin/test-runner-commands": "~25.2.7",
+    "@vaadin/chai-plugins": "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/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/aria-modal-controller.js

@@ -13,6 +13,9 @@ import { hideOthers } from './aria-hidden.js';
  * consumer web component. This is done in to ensure the controller only does one thing.
  */
 export class AriaModalController {
+  /** @type {Function | null} */
+  #showOthers = null;
+
   /**
    * @param {HTMLElement} host
    */
@@ -42,7 +45,7 @@ export class AriaModalController {
    */
   showModal() {
     const targets = this.callback();
-    this.__showOthers = hideOthers(targets);
+    this.#showOthers = hideOthers(targets);
   }
 
   /**
@@ -50,9 +53,9 @@ export class AriaModalController {
    * controller hosts on the page activated by using `showModal()` call.
    */
   close() {
-    if (this.__showOthers) {
-      this.__showOthers();
-      this.__showOthers = null;
+    if (this.#showOthers) {
+      this.#showOthers();
+      this.#showOthers = 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,16 +3,46 @@
  * 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:
  * either the component itself or slotted `<input>` element.
  */
 export class FieldAriaController {
+  /** @type {HTMLElement | undefined} */
+  #target;
+
+  /** @type {boolean} */
+  #required = false;
+
+  /** @type {string | null | undefined} */
+  #label;
+
+  /** @type {string | null | undefined} */
+  #labelledBy;
+
+  /** @type {string | null | undefined} */
+  #describedBy;
+
+  /** @type {string | null | undefined} */
+  #errorId;
+
+  /** @type {string | null | undefined} */
+  #helperId;
+
+  /** @type {string[]} */
+  #ariaLabelledByAttributeIds = [];
+
+  /** @type {string[]} */
+  #ariaDescribedByAttributeIds = [];
+
   constructor(host) {
     this.host = host;
-    this.__required = false;
   }
 
   /**
@@ -21,16 +51,11 @@ export class FieldAriaController {
    * @param {HTMLElement} target
    */
   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.#target = target;
+    this.#updateAriaLabelAttribute();
+    this.#updateAriaLabelledByAttribute();
+    this.#updateAriaDescribedByAttribute();
+    this.#updateAriaRequiredAttribute();
   }
 
   /**
@@ -41,8 +66,8 @@ export class FieldAriaController {
    * @param {boolean} required
    */
   setRequired(required) {
-    this.__setAriaRequiredAttribute(required);
-    this.__required = required;
+    this.#required = required;
+    this.#updateAriaRequiredAttribute();
   }
 
   /**
@@ -52,120 +77,97 @@ export class FieldAriaController {
    *
    * @param {string | null | undefined} label
    */
-  setAriaLabel(label) {
-    this.__setAriaLabelToAttribute(label);
-    this.__label = label;
+  setLabel(label) {
+    this.#label = label;
+    this.#updateAriaLabelAttribute();
   }
 
   /**
-   * Links the target element with a slotted label element
-   * via the target's attribute `aria-labelledby`.
-   *
-   * To unlink the previous slotted label element, pass `null` as `labelId`.
+   * Links the target element to one or more elements via the `aria-labelledby` attribute.
    *
-   * @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.#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.
+   * 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`.
-   *
-   * @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.#helperId = helperId;
+    this.#updateAriaDescribedByAttribute();
   }
 
-  /**
-   * @param {string | null | undefined} label
-   * @private
-   * */
-  __setAriaLabelToAttribute(label) {
-    if (!this.__target) {
+  #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
-   * @private
-   */
-  __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
-   * @private
-   */
-  __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
-   * @private
-   */
-  __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
-   * @private
-   */
-  __setAriaRequiredAttribute(required) {
-    if (!this.__target) {
+  #updateAriaRequiredAttribute() {
+    if (!this.#target) {
       return;
     }
 
-    if (['input', 'textarea'].includes(this.__target.localName)) {
+    if (['input', 'textarea'].includes(this.#target.localName)) {
       // Native <input> or <textarea>, required is enough
       return;
     }
 
-    if (required) {
-      this.__target.setAttribute('aria-required', 'true');
-    } else {
-      this.__target.removeAttribute('aria-required');
-    }
+    setOrRemoveAttribute(this.#target, 'aria-required', this.#required);
   }
 }

package/src/focus-trap-controller.d.ts

@@ -20,6 +20,11 @@ export class FocusTrapController implements ReactiveController {
    */
   host: HTMLElement;
 
+  /**
+   * A node for trapping focus in.
+   */
+  trapNode: HTMLElement | null;
+
   constructor(node: HTMLElement);
 
   hostConnected(): void;

package/src/focus-trap-controller.js

@@ -3,7 +3,7 @@
  * Copyright (c) 2021 - 2026 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { getFocusableElements, isElementFocused, isKeyboardActive } from './focus-utils.js';
+import { getTabbableElements, isElementFocused, isKeyboardActive } from './focus-utils.js';
 
 const instances = [];
 
@@ -17,8 +17,8 @@ const instances = [];
 export function getActiveTrappingNode(element) {
   // Iterate backwards since instances are ordered outer-to-inner (push/pop)
   for (let i = instances.length - 1; i >= 0; i--) {
-    if (instances[i].__trapNode?.contains(element)) {
-      return instances[i].__trapNode;
+    if (instances[i].trapNode?.contains(element)) {
+      return instances[i].trapNode;
     }
   }
   return null;
@@ -28,6 +28,13 @@ export function getActiveTrappingNode(element) {
  * A controller for trapping focus within a DOM node.
  */
 export class FocusTrapController {
+  /**
+   * A node for trapping focus in.
+   *
+   * @type {HTMLElement | null}
+   */
+  trapNode = null;
+
   /**
    * @param {HTMLElement} host
    */
@@ -38,45 +45,33 @@ export class FocusTrapController {
      * @type {HTMLElement}
      */
     this.host = host;
-
-    /**
-     * A node for trapping focus in.
-     *
-     * @type {HTMLElement | null}
-     * @private
-     */
-    this.__trapNode = null;
-
-    this.__onKeyDown = this.__onKeyDown.bind(this);
   }
 
   /**
    * An array of tab-ordered focusable elements inside the trap node.
    *
    * @return {HTMLElement[]}
-   * @private
    */
-  get __focusableElements() {
-    return getFocusableElements(this.__trapNode);
+  get #focusableElements() {
+    return getTabbableElements(this.trapNode);
   }
 
   /**
    * The index of the element inside the trap node that currently has focus.
    *
    * @return {HTMLElement | undefined}
-   * @private
    */
-  get __focusedElementIndex() {
-    const focusableElements = this.__focusableElements;
+  get #focusedElementIndex() {
+    const focusableElements = this.#focusableElements;
     return focusableElements.indexOf(focusableElements.filter(isElementFocused).pop());
   }
 
   hostConnected() {
-    document.addEventListener('keydown', this.__onKeyDown);
+    document.addEventListener('keydown', this.#onKeyDown);
   }
 
   hostDisconnected() {
-    document.removeEventListener('keydown', this.__onKeyDown);
+    document.removeEventListener('keydown', this.#onKeyDown);
   }
 
   /**
@@ -94,17 +89,17 @@ export class FocusTrapController {
    * @param {HTMLElement} trapNode
    */
   trapFocus(trapNode) {
-    this.__trapNode = trapNode;
+    this.trapNode = trapNode;
 
-    if (this.__focusableElements.length === 0) {
-      this.__trapNode = null;
+    if (this.#focusableElements.length === 0) {
+      this.trapNode = null;
       throw new Error('The trap node should have at least one focusable descendant or be focusable itself.');
     }
 
     instances.push(this);
 
-    if (this.__focusedElementIndex === -1) {
-      this.__focusableElements[0].focus({ focusVisible: isKeyboardActive() });
+    if (this.#focusedElementIndex === -1) {
+      this.#focusableElements[0].focus({ focusVisible: isKeyboardActive() });
     }
   }
 
@@ -113,7 +108,7 @@ export class FocusTrapController {
    * so that it becomes possible to tab outside the trap node.
    */
   releaseFocus() {
-    this.__trapNode = null;
+    this.trapNode = null;
 
     instances.pop();
   }
@@ -127,10 +122,9 @@ export class FocusTrapController {
    * When no prev element to focus, the method moves focus to the last focusable element.
    *
    * @param {KeyboardEvent} event
-   * @private
    */
-  __onKeyDown(event) {
-    if (!this.__trapNode) {
+  #onKeyDown = (event) => {
+    if (!this.trapNode) {
       return;
     }
 
@@ -148,9 +142,9 @@ export class FocusTrapController {
       event.preventDefault();
 
       const backward = event.shiftKey;
-      this.__focusNextElement(backward);
+      this.#focusNextElement(backward);
     }
-  }
+  };
 
   /**
    * - Moves focus to the next focusable element if `backward === false`.
@@ -161,12 +155,11 @@ export class FocusTrapController {
    * If no focusable elements, the method returns immediately.
    *
    * @param {boolean} backward
-   * @private
    */
-  __focusNextElement(backward = false) {
-    const focusableElements = this.__focusableElements;
+  #focusNextElement(backward = false) {
+    const focusableElements = this.#focusableElements;
     const step = backward ? -1 : 1;
-    const currentIndex = this.__focusedElementIndex;
+    const currentIndex = this.#focusedElementIndex;
     const nextIndex = (focusableElements.length + currentIndex + step) % focusableElements.length;
     const element = focusableElements[nextIndex];
     element.focus({ focusVisible: true });

package/src/focus-utils.d.ts

@@ -26,7 +26,8 @@ export declare function isKeyboardActive(): boolean;
 export declare function isElementHidden(element: HTMLElement): boolean;
 
 /**
- * Returns true if the element is focusable, otherwise false.
+ * Returns true if the element is focusable, i.e. can be focused with a
+ * mouse click or a `focus()` call, otherwise false.
  *
  * The list of focusable elements is taken from http://stackoverflow.com/a/1600194/4228703.
  * However, there isn't a definite list, it's up to the browser.
@@ -54,4 +55,4 @@ export declare function isElementFocused(element: HTMLElement): boolean;
  *
  * The method traverses nodes in shadow DOM trees too if any.
  */
-export declare function getFocusableElements(element: HTMLElement): HTMLElement[];
+export declare function getTabbableElements(element: HTMLElement): HTMLElement[];

package/src/focus-utils.js

@@ -165,7 +165,8 @@ export function isElementHidden(element) {
 }
 
 /**
- * Returns true if the element is focusable, otherwise false.
+ * Returns true if the element is focusable, i.e. can be focused with a
+ * mouse click or a `focus()` call, otherwise false.
  *
  * The list of focusable elements is taken from http://stackoverflow.com/a/1600194/4228703.
  * However, there isn't a definite list, it's up to the browser.
@@ -184,11 +185,6 @@ export function isElementHidden(element) {
  * @return {boolean}
  */
 export function isElementFocusable(element) {
-  // The element cannot be focused if its `tabindex` attribute is set to `-1`.
-  if (element.matches('[tabindex="-1"]')) {
-    return false;
-  }
-
   // Elements that cannot be focused if they have a `disabled` attribute.
   if (element.matches('input, select, textarea, button, object')) {
     return element.matches(':not([disabled])');
@@ -271,7 +267,7 @@ function collectFocusableNodes(node, result) {
  * @param {HTMLElement} element
  * @return {HTMLElement[]}
  */
-export function getFocusableElements(element) {
+export function getTabbableElements(element) {
   const focusableElements = [];
   const needsSortByTabIndex = collectFocusableNodes(element, focusableElements);
   // If there is at least one element with tabindex > 0,

package/src/list-mixin.d.ts

@@ -35,6 +35,11 @@ export declare class ListMixinClass {
    */
   orientation: 'horizontal' | 'vertical';
 
+  /**
+   * Used for mixin detection because `instanceof` does not work with mixins.
+   */
+  protected _hasVaadinListMixin: boolean;
+
   /**
    * A read-only list of items from which a selection can be made.
    * It is populated from the elements passed to the light DOM,

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';
@@ -77,6 +78,16 @@ export const ListMixin = (superClass) =>
       return ['_enhanceItems(items, orientation, selected, disabled)'];
     }
 
+    constructor() {
+      super();
+
+      /**
+       * Used for mixin detection because `instanceof` does not work with mixins.
+       * @protected
+       */
+      this._hasVaadinListMixin = true;
+    }
+
     /**
      * @return {boolean}
      * @protected
@@ -153,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);
-}