@vaadin/a11y-base 24.1.0-alpha3 → 24.1.0-alpha5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/a11y-base",
-  "version": "24.1.0-alpha3",
+  "version": "24.1.0-alpha5",
   "publishConfig": {
     "access": "public"
   },
@@ -32,7 +32,7 @@
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/component-base": "24.1.0-alpha3",
+    "@vaadin/component-base": "24.1.0-alpha5",
     "lit": "^2.0.0"
   },
   "devDependencies": {
@@ -40,5 +40,5 @@
     "@vaadin/testing-helpers": "^0.4.0",
     "sinon": "^13.0.2"
   },
-  "gitHead": "077b4a8e8fff063b9eba4581af81f9e152cb852d"
+  "gitHead": "1ab6c977fe239d94aac5f39940c1a4722ad4bb63"
 }

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

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright (c) 2023 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

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * Copyright (c) 2023 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
+ *
+ * @returns {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
+ * @param {boolean} storeValue whether or not the current value of the attribute should be stored on the map
+ * @returns
+ */
+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
+    storedValues.delete(oldId);
+    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);
+}

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

@@ -28,13 +28,20 @@ export class FieldAriaController {
    */
   setRequired(required: boolean): void;
 
+  /**
+   * Defines the `aria-label` attribute of the target element.
+   *
+   * To remove the attribute, pass `null` as `label`.
+   */
+  setAriaLabel(label: string | null): void;
+
   /**
    * 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`.
    */
-  setLabelId(labelId: string | null): void;
+  setLabelId(labelId: string | null, fromUser: boolean | null): void;
 
   /**
    * Links the target element with a slotted error element via the target's attribute:

package/src/field-aria-controller.js

@@ -3,7 +3,11 @@
  * Copyright (c) 2021 - 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { addValueToAttribute, removeValueFromAttribute } from '@vaadin/component-base/src/dom-utils.js';
+import {
+  removeAriaIDReference,
+  restoreGeneratedAriaIDReference,
+  setAriaIDReference,
+} from '@vaadin/a11y-base/src/aria-id-reference.js';
 
 /**
  * A controller for managing ARIA attributes for a field element:
@@ -36,6 +40,7 @@ export class FieldAriaController {
     this.__setLabelIdToAriaAttribute(this.__labelId);
     this.__setErrorIdToAriaAttribute(this.__errorId);
     this.__setHelperIdToAriaAttribute(this.__helperId);
+    this.setAriaLabel(this.__label);
   }
 
   /**
@@ -50,6 +55,18 @@ export class FieldAriaController {
     this.__required = required;
   }
 
+  /**
+   * Defines the `aria-label` attribute of the target element.
+   *
+   * To remove the attribute, pass `null` as `label`.
+   *
+   * @param {string | null | undefined} label
+   */
+  setAriaLabel(label) {
+    this.__setAriaLabelToAttribute(label);
+    this.__label = label;
+  }
+
   /**
    * Links the target element with a slotted label element
    * via the target's attribute `aria-labelledby`.
@@ -58,9 +75,14 @@ export class FieldAriaController {
    *
    * @param {string | null} labelId
    */
-  setLabelId(labelId) {
-    this.__setLabelIdToAriaAttribute(labelId, this.__labelId);
-    this.__labelId = labelId;
+  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;
+    }
   }
 
   /**
@@ -91,13 +113,31 @@ export class FieldAriaController {
     this.__helperId = helperId;
   }
 
+  /**
+   * @param {string | null | undefined} label
+   * @private
+   * */
+  __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');
+    }
+  }
+
   /**
    * @param {string | null | undefined} labelId
    * @param {string | null | undefined} oldLabelId
+   * @param {boolean | null | undefined} fromUser
    * @private
    */
-  __setLabelIdToAriaAttribute(labelId, oldLabelId) {
-    this.__setAriaAttributeId('aria-labelledby', labelId, oldLabelId);
+  __setLabelIdToAriaAttribute(labelId, oldLabelId, fromUser) {
+    setAriaIDReference(this.__target, 'aria-labelledby', { newId: labelId, oldId: oldLabelId, fromUser });
   }
 
   /**
@@ -108,11 +148,8 @@ export class FieldAriaController {
   __setErrorIdToAriaAttribute(errorId, oldErrorId) {
     // For groups, add all IDs to aria-labelledby rather than aria-describedby -
     // that should guarantee that it's announced when the group is entered.
-    if (this.__isGroupField) {
-      this.__setAriaAttributeId('aria-labelledby', errorId, oldErrorId);
-    } else {
-      this.__setAriaAttributeId('aria-describedby', errorId, oldErrorId);
-    }
+    const ariaAttribute = this.__isGroupField ? 'aria-labelledby' : 'aria-describedby';
+    setAriaIDReference(this.__target, ariaAttribute, { newId: errorId, oldId: oldErrorId, fromUser: false });
   }
 
   /**
@@ -123,11 +160,8 @@ export class FieldAriaController {
   __setHelperIdToAriaAttribute(helperId, oldHelperId) {
     // For groups, add all IDs to aria-labelledby rather than aria-describedby -
     // that should guarantee that it's announced when the group is entered.
-    if (this.__isGroupField) {
-      this.__setAriaAttributeId('aria-labelledby', helperId, oldHelperId);
-    } else {
-      this.__setAriaAttributeId('aria-describedby', helperId, oldHelperId);
-    }
+    const ariaAttribute = this.__isGroupField ? 'aria-labelledby' : 'aria-describedby';
+    setAriaIDReference(this.__target, ariaAttribute, { newId: helperId, oldId: oldHelperId, fromUser: false });
   }
 
   /**
@@ -150,23 +184,4 @@ export class FieldAriaController {
       this.__target.removeAttribute('aria-required');
     }
   }
-
-  /**
-   * @param {string | null | undefined} newId
-   * @param {string | null | undefined} oldId
-   * @private
-   */
-  __setAriaAttributeId(attr, newId, oldId) {
-    if (!this.__target) {
-      return;
-    }
-
-    if (oldId) {
-      removeValueFromAttribute(this.__target, attr, oldId);
-    }
-
-    if (newId) {
-      addValueToAttribute(this.__target, attr, newId);
-    }
-  }
 }

package/src/focus-utils.d.ts

@@ -4,6 +4,12 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 
+/**
+ * Returns the actually focused element by traversing shadow
+ * trees recursively to ensure it's the leaf element.
+ */
+export declare function getDeepActiveElement(): Element;
+
 /**
  * Returns true if the window has received a keydown
  * event since the last mousedown event.

package/src/focus-utils.js

@@ -26,6 +26,20 @@ window.addEventListener(
   { capture: true },
 );
 
+/**
+ * Returns the actually focused element by traversing shadow
+ * trees recursively to ensure it's the leaf element.
+ *
+ * @return {Element}
+ */
+export function getDeepActiveElement() {
+  let host = document.activeElement || document.body;
+  while (host.shadowRoot && host.shadowRoot.activeElement) {
+    host = host.shadowRoot.activeElement;
+  }
+  return host;
+}
+
 /**
  * Returns true if the window has received a keydown
  * event since the last mousedown event.