@vaadin/a11y-base 24.1.0-alpha1

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

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * A controller for managing ARIA attributes for a field element:
+ * either the component itself or slotted `<input>` element.
+ */
+export class FieldAriaController {
+  /**
+   * The controller host element.
+   */
+  host: HTMLElement;
+
+  constructor(host: HTMLElement);
+
+  /**
+   * Sets a target element to which ARIA attributes are added.
+   */
+  setTarget(target: HTMLElement): void;
+
+  /**
+   * Toggles the `aria-required` attribute on the target element
+   * if the target is the host component (e.g. a field group).
+   * Otherwise, it does nothing.
+   */
+  setRequired(required: boolean): 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;
+
+  /**
+   * 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.
+   *
+   * To unlink the previous slotted error element, pass `null` as `errorId`.
+   */
+  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.
+   *
+   * To unlink the previous slotted helper element, pass `null` as `helperId`.
+   */
+  setHelperId(helperId: string | null): void;
+}

package/src/field-aria-controller.js

@@ -0,0 +1,172 @@
+/**
+ * @license
+ * 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';
+
+/**
+ * A controller for managing ARIA attributes for a field element:
+ * either the component itself or slotted `<input>` element.
+ */
+export class FieldAriaController {
+  constructor(host) {
+    this.host = host;
+    this.__required = false;
+  }
+
+  /**
+   * `true` if the target element is the host component itself, `false` otherwise.
+   *
+   * @return {boolean}
+   * @private
+   */
+  get __isGroupField() {
+    return this.__target === this.host;
+  }
+
+  /**
+   * Sets a target element to which ARIA attributes are added.
+   *
+   * @param {HTMLElement} target
+   */
+  setTarget(target) {
+    this.__target = target;
+    this.__setAriaRequiredAttribute(this.__required);
+    this.__setLabelIdToAriaAttribute(this.__labelId);
+    this.__setErrorIdToAriaAttribute(this.__errorId);
+    this.__setHelperIdToAriaAttribute(this.__helperId);
+  }
+
+  /**
+   * Toggles the `aria-required` attribute on the target element
+   * if the target is the host component (e.g. a field group).
+   * Otherwise, it does nothing.
+   *
+   * @param {boolean} required
+   */
+  setRequired(required) {
+    this.__setAriaRequiredAttribute(required);
+    this.__required = required;
+  }
+
+  /**
+   * 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`.
+   *
+   * @param {string | null} labelId
+   */
+  setLabelId(labelId) {
+    this.__setLabelIdToAriaAttribute(labelId, this.__labelId);
+    this.__labelId = labelId;
+  }
+
+  /**
+   * 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.
+   *
+   * To unlink the previous slotted error element, pass `null` as `errorId`.
+   *
+   * @param {string | null} errorId
+   */
+  setErrorId(errorId) {
+    this.__setErrorIdToAriaAttribute(errorId, this.__errorId);
+    this.__errorId = errorId;
+  }
+
+  /**
+   * 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`.
+   *
+   * @param {string | null} helperId
+   */
+  setHelperId(helperId) {
+    this.__setHelperIdToAriaAttribute(helperId, this.__helperId);
+    this.__helperId = helperId;
+  }
+
+  /**
+   * @param {string | null | undefined} labelId
+   * @param {string | null | undefined} oldLabelId
+   * @private
+   */
+  __setLabelIdToAriaAttribute(labelId, oldLabelId) {
+    this.__setAriaAttributeId('aria-labelledby', labelId, oldLabelId);
+  }
+
+  /**
+   * @param {string | null | undefined} errorId
+   * @param {string | null | undefined} oldErrorId
+   * @private
+   */
+  __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);
+    }
+  }
+
+  /**
+   * @param {string | null | undefined} helperId
+   * @param {string | null | undefined} oldHelperId
+   * @private
+   */
+  __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);
+    }
+  }
+
+  /**
+   * @param {boolean} required
+   * @private
+   */
+  __setAriaRequiredAttribute(required) {
+    if (!this.__target) {
+      return;
+    }
+
+    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');
+    }
+  }
+
+  /**
+   * @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-mixin.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+
+/**
+ * A mixin to handle `focused` and `focus-ring` attributes based on focus.
+ */
+export declare function FocusMixin<T extends Constructor<HTMLElement>>(base: T): Constructor<FocusMixinClass> & T;
+
+export declare class FocusMixinClass {
+  protected readonly _keyboardActive: boolean;
+
+  /**
+   * Override to change how focused and focus-ring attributes are set.
+   */
+  protected _setFocused(focused: boolean): void;
+
+  /**
+   * Override to define if the field receives focus based on the event.
+   */
+  protected _shouldSetFocus(event: FocusEvent): boolean;
+
+  /**
+   * Override to define if the field loses focus based on the event.
+   */
+  protected _shouldRemoveFocus(event: FocusEvent): boolean;
+}

package/src/focus-mixin.js

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { dedupingMixin } from '@polymer/polymer/lib/utils/mixin.js';
+import { isKeyboardActive } from './focus-utils.js';
+
+/**
+ * A mixin to handle `focused` and `focus-ring` attributes based on focus.
+ *
+ * @polymerMixin
+ */
+export const FocusMixin = dedupingMixin(
+  (superclass) =>
+    class FocusMixinClass extends superclass {
+      /**
+       * @protected
+       * @return {boolean}
+       */
+      get _keyboardActive() {
+        return isKeyboardActive();
+      }
+
+      /** @protected */
+      ready() {
+        this.addEventListener('focusin', (e) => {
+          if (this._shouldSetFocus(e)) {
+            this._setFocused(true);
+          }
+        });
+
+        this.addEventListener('focusout', (e) => {
+          if (this._shouldRemoveFocus(e)) {
+            this._setFocused(false);
+          }
+        });
+
+        // In super.ready() other 'focusin' and 'focusout' listeners might be
+        // added, so we call it after our own ones to ensure they execute first.
+        // Issue to watch out: when incorrect, <vaadin-combo-box> refocuses the
+        // input field on iOS after "Done" is pressed.
+        super.ready();
+      }
+
+      /** @protected */
+      disconnectedCallback() {
+        super.disconnectedCallback();
+
+        // In non-Chrome browsers, blur does not fire on the element when it is disconnected.
+        // reproducible in `<vaadin-date-picker>` when closing on `Cancel` or `Today` click.
+        if (this.hasAttribute('focused')) {
+          this._setFocused(false);
+        }
+      }
+
+      /**
+       * Override to change how focused and focus-ring attributes are set.
+       *
+       * @param {boolean} focused
+       * @protected
+       */
+      _setFocused(focused) {
+        this.toggleAttribute('focused', focused);
+
+        // Focus-ring is true when the element was focused from the keyboard.
+        // Focus Ring [A11ycasts]: https://youtu.be/ilj2P5-5CjI
+        this.toggleAttribute('focus-ring', focused && this._keyboardActive);
+      }
+
+      /**
+       * Override to define if the field receives focus based on the event.
+       *
+       * @param {FocusEvent} _event
+       * @return {boolean}
+       * @protected
+       */
+      _shouldSetFocus(_event) {
+        return true;
+      }
+
+      /**
+       * Override to define if the field loses focus based on the event.
+       *
+       * @param {FocusEvent} _event
+       * @return {boolean}
+       * @protected
+       */
+      _shouldRemoveFocus(_event) {
+        return true;
+      }
+    },
+);

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

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { ReactiveController } from 'lit';
+
+/**
+ * A controller for trapping focus within a DOM node.
+ */
+export class FocusTrapController implements ReactiveController {
+  /**
+   * The controller host element.
+   */
+  host: HTMLElement;
+
+  constructor(node: HTMLElement);
+
+  hostConnected(): void;
+
+  hostDisconnected(): void;
+
+  /**
+   * Activates a focus trap for a DOM node that will prevent focus from escaping the node.
+   * The trap can be deactivated with the `.releaseFocus()` method.
+   *
+   * If focus is initially outside the trap, the method will move focus inside,
+   * on the first focusable element of the trap in the tab order.
+   * The first focusable element can be the trap node itself if it is focusable
+   * and comes first in the tab order.
+   */
+  trapFocus(trapNode: HTMLElement): void;
+
+  /**
+   * Deactivates the focus trap set with the `.trapFocus()` method
+   * so that it becomes possible to tab outside the trap node.
+   */
+  releaseFocus(): void;
+}

package/src/focus-trap-controller.js

@@ -0,0 +1,155 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { getFocusableElements, isElementFocused } from './focus-utils.js';
+
+const instances = [];
+
+/**
+ * A controller for trapping focus within a DOM node.
+ */
+export class FocusTrapController {
+  /**
+   * @param {HTMLElement} host
+   */
+  constructor(host) {
+    /**
+     * The controller host element.
+     *
+     * @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);
+  }
+
+  /**
+   * The index of the element inside the trap node that currently has focus.
+   *
+   * @return {HTMLElement | undefined}
+   * @private
+   */
+  get __focusedElementIndex() {
+    const focusableElements = this.__focusableElements;
+    return focusableElements.indexOf(focusableElements.filter(isElementFocused).pop());
+  }
+
+  hostConnected() {
+    document.addEventListener('keydown', this.__onKeyDown);
+  }
+
+  hostDisconnected() {
+    document.removeEventListener('keydown', this.__onKeyDown);
+  }
+
+  /**
+   * Activates a focus trap for a DOM node that will prevent focus from escaping the node.
+   * The trap can be deactivated with the `.releaseFocus()` method.
+   *
+   * If focus is initially outside the trap, the method will move focus inside,
+   * on the first focusable element of the trap in the tab order.
+   * The first focusable element can be the trap node itself if it is focusable
+   * and comes first in the tab order.
+   *
+   * If there are no focusable elements, the method will throw an exception
+   * and the trap will not be set.
+   *
+   * @param {HTMLElement} trapNode
+   */
+  trapFocus(trapNode) {
+    this.__trapNode = trapNode;
+
+    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();
+    }
+  }
+
+  /**
+   * Deactivates the focus trap set with the `.trapFocus()` method
+   * so that it becomes possible to tab outside the trap node.
+   */
+  releaseFocus() {
+    this.__trapNode = null;
+
+    instances.pop();
+  }
+
+  /**
+   * A `keydown` event handler that manages tabbing navigation when the trap is enabled.
+   *
+   * - Moves focus to the next focusable element of the trap on `Tab` press.
+   * When no next element to focus, the method moves focus to the first focusable element.
+   * - Moves focus to the prev focusable element of the trap on `Shift+Tab` press.
+   * When no prev element to focus, the method moves focus to the last focusable element.
+   *
+   * @param {KeyboardEvent} event
+   * @private
+   */
+  __onKeyDown(event) {
+    if (!this.__trapNode) {
+      return;
+    }
+
+    // Only handle events for the last instance
+    if (this !== Array.from(instances).pop()) {
+      return;
+    }
+
+    if (event.key === 'Tab') {
+      event.preventDefault();
+
+      const backward = event.shiftKey;
+      this.__focusNextElement(backward);
+    }
+  }
+
+  /**
+   * - Moves focus to the next focusable element if `backward === false`.
+   * When no next element to focus, the method moves focus to the first focusable element.
+   * - Moves focus to the prev focusable element if `backward === true`.
+   * When no prev element to focus the method moves focus to the last focusable element.
+   *
+   * If no focusable elements, the method returns immediately.
+   *
+   * @param {boolean} backward
+   * @private
+   */
+  __focusNextElement(backward = false) {
+    const focusableElements = this.__focusableElements;
+    const step = backward ? -1 : 1;
+    const currentIndex = this.__focusedElementIndex;
+    const nextIndex = (focusableElements.length + currentIndex + step) % focusableElements.length;
+    const element = focusableElements[nextIndex];
+    element.focus();
+    if (element.localName === 'input') {
+      element.select();
+    }
+  }
+}

package/src/focus-utils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * Returns true if the window has received a keydown
+ * event since the last mousedown event.
+ */
+export declare function isKeyboardActive(): boolean;
+
+/**
+ * Returns true if the element is hidden, false otherwise.
+ *
+ * An element is treated as hidden when any of the following conditions are met:
+ * - the element itself or one of its ancestors has `display: none`.
+ * - the element has or inherits `visibility: hidden`.
+ */
+export declare function isElementHidden(element: HTMLElement): boolean;
+
+/**
+ * Returns true if the element is focusable, 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.
+ * The only standard we have is DOM Level 2 HTML https://www.w3.org/TR/DOM-Level-2-HTML/html.html,
+ * according to which the only elements that have a `focus()` method are:
+ * - HTMLInputElement
+ * - HTMLSelectElement
+ * - HTMLTextAreaElement
+ * - HTMLAnchorElement
+ *
+ * This notably omits HTMLButtonElement and HTMLAreaElement.
+ * Referring to these tests with tabbables in different browsers
+ * http://allyjs.io/data-tables/focusable.html
+ */
+export declare function isElementFocusable(element: HTMLElement): boolean;
+
+/**
+ * Returns true if the element is focused, false otherwise.
+ */
+export declare function isElementFocused(element: HTMLElement): boolean;
+
+/**
+ * Returns a tab-ordered array of focusable elements for a root element.
+ * The resulting array will include the root element if it is focusable.
+ *
+ * The method traverses nodes in shadow DOM trees too if any.
+ */
+export declare function getFocusableElements(element: HTMLElement): HTMLElement[];