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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/a11y-base",
-  "version": "25.3.0-alpha7",
+  "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-alpha7",
+    "@vaadin/component-base": "25.3.0-alpha8",
     "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-alpha8",
+    "@vaadin/test-runner-commands": "25.3.0-alpha8",
     "@vaadin/testing-helpers": "^2.0.0",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
-  "gitHead": "ae7b9823df5598faebd7a482993029ee489c35ae"
+  "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;
+}