@vaadin/a11y-base 25.3.0-alpha6 → 25.3.0-alpha8

package/package.json

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

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/field-aria-controller.js

@@ -10,9 +10,29 @@ import { removeAriaIDReference, restoreGeneratedAriaIDReference, setAriaIDRefere
  * 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} */
+  #labelId;
+
+  /** @type {string | null | undefined} */
+  #labelIdFromUser;
+
+  /** @type {string | null | undefined} */
+  #errorId;
+
+  /** @type {string | null | undefined} */
+  #helperId;
+
   constructor(host) {
     this.host = host;
-    this.__required = false;
   }
 
   /**
@@ -21,16 +41,16 @@ 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.#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.#setErrorIdToAriaAttribute(this.#errorId);
+    this.#setHelperIdToAriaAttribute(this.#helperId);
+    this.setAriaLabel(this.#label);
   }
 
   /**
@@ -41,8 +61,8 @@ export class FieldAriaController {
    * @param {boolean} required
    */
   setRequired(required) {
-    this.__setAriaRequiredAttribute(required);
-    this.__required = required;
+    this.#setAriaRequiredAttribute(required);
+    this.#required = required;
   }
 
   /**
@@ -53,8 +73,8 @@ export class FieldAriaController {
    * @param {string | null | undefined} label
    */
   setAriaLabel(label) {
-    this.__setAriaLabelToAttribute(label);
-    this.__label = label;
+    this.#setAriaLabelToAttribute(label);
+    this.#label = label;
   }
 
   /**
@@ -66,12 +86,12 @@ export class FieldAriaController {
    * @param {string | null} labelId
    */
   setLabelId(labelId, fromUser = false) {
-    const oldLabelId = fromUser ? this.__labelIdFromUser : this.__labelId;
-    this.__setLabelIdToAriaAttribute(labelId, oldLabelId, fromUser);
+    const oldLabelId = fromUser ? this.#labelIdFromUser : this.#labelId;
+    this.#setLabelIdToAriaAttribute(labelId, oldLabelId, fromUser);
     if (fromUser) {
-      this.__labelIdFromUser = labelId;
+      this.#labelIdFromUser = labelId;
     } else {
-      this.__labelId = labelId;
+      this.#labelId = labelId;
     }
   }
 
@@ -85,8 +105,8 @@ export class FieldAriaController {
    * @param {string | null} errorId
    */
   setErrorId(errorId) {
-    this.__setErrorIdToAriaAttribute(errorId, this.__errorId);
-    this.__errorId = errorId;
+    this.#setErrorIdToAriaAttribute(errorId, this.#errorId);
+    this.#errorId = errorId;
   }
 
   /**
@@ -99,24 +119,23 @@ export class FieldAriaController {
    * @param {string | null} helperId
    */
   setHelperId(helperId) {
-    this.__setHelperIdToAriaAttribute(helperId, this.__helperId);
-    this.__helperId = helperId;
+    this.#setHelperIdToAriaAttribute(helperId, this.#helperId);
+    this.#helperId = helperId;
   }
 
   /**
    * @param {string | null | undefined} label
-   * @private
-   * */
-  __setAriaLabelToAttribute(label) {
-    if (!this.__target) {
+   */
+  #setAriaLabelToAttribute(label) {
+    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');
+      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');
     }
   }
 
@@ -124,48 +143,44 @@ export class FieldAriaController {
    * @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 });
+  #setLabelIdToAriaAttribute(labelId, oldLabelId, fromUser) {
+    setAriaIDReference(this.#target, 'aria-labelledby', { newId: labelId, oldId: oldLabelId, fromUser });
   }
 
   /**
    * @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 });
+  #setErrorIdToAriaAttribute(errorId, oldErrorId) {
+    setAriaIDReference(this.#target, 'aria-describedby', { newId: errorId, oldId: oldErrorId, fromUser: false });
   }
 
   /**
    * @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 });
+  #setHelperIdToAriaAttribute(helperId, oldHelperId) {
+    setAriaIDReference(this.#target, 'aria-describedby', { newId: helperId, oldId: oldHelperId, fromUser: false });
   }
 
   /**
    * @param {boolean} required
-   * @private
    */
-  __setAriaRequiredAttribute(required) {
-    if (!this.__target) {
+  #setAriaRequiredAttribute(required) {
+    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');
+      this.#target.setAttribute('aria-required', 'true');
     } else {
-      this.__target.removeAttribute('aria-required');
+      this.#target.removeAttribute('aria-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

@@ -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 getTabbableElements(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 });