@vaadin/a11y-base 24.1.0-alpha1

package/src/aria-hidden.js

@@ -0,0 +1,240 @@
+/**
+ * @license
+ * Copyright (c) 2017 Anton Korzunov
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * @fileoverview
+ *
+ * This module includes JS code copied from the `aria-hidden` package:
+ * https://github.com/theKashey/aria-hidden/blob/master/src/index.ts
+ */
+
+/** @type {WeakMap<Element, number>} */
+let counterMap = new WeakMap();
+
+/** @type {WeakMap<Element, boolean>} */
+let uncontrolledNodes = new WeakMap();
+
+/** @type {Record<string, WeakMap<Element, number>>} */
+let markerMap = {};
+
+/** @type {number} */
+let lockCount = 0;
+
+/**
+ * @param {Element | Shadow} node
+ * @return {Element | null}
+ */
+const unwrapHost = (node) => (node ? node.host || unwrapHost(node.parentNode) : null);
+
+/**
+ * @param {?Node} node
+ * @return {boolean}
+ */
+const isElement = (node) => node && node.nodeType === Node.ELEMENT_NODE;
+
+/**
+ * @param  {...unknown} args
+ */
+const logError = (...args) => {
+  console.error(`Error: ${args.join(' ')}. Skip setting aria-hidden.`);
+};
+
+/**
+ * @param {HTMLElement} parent
+ * @param {Element[]} targets
+ * @return {Element[]}
+ */
+const correctTargets = (parent, targets) => {
+  if (!isElement(parent)) {
+    logError(parent, 'is not a valid element');
+    return [];
+  }
+
+  return targets
+    .map((target) => {
+      if (!isElement(target)) {
+        logError(target, 'is not a valid element');
+        return null;
+      }
+
+      if (parent.contains(target)) {
+        return target;
+      }
+
+      const correctedTarget = unwrapHost(target);
+      if (correctedTarget && parent.contains(correctedTarget)) {
+        return correctedTarget;
+      }
+
+      logError(target, 'is not contained inside', parent);
+      return null;
+    })
+    .filter((x) => Boolean(x));
+};
+
+/**
+ * Marks everything except given node(or nodes) as aria-hidden
+ * @param {Element | Element[]} originalTarget - elements to keep on the page
+ * @param {HTMLElement} [parentNode] - top element, defaults to document.body
+ * @param {String} [markerName] - a special attribute to mark every node
+ * @param {String} [controlAttribute] - html Attribute to control
+ * @return {Function}
+ */
+const applyAttributeToOthers = (originalTarget, parentNode, markerName, controlAttribute) => {
+  const targets = correctTargets(parentNode, Array.isArray(originalTarget) ? originalTarget : [originalTarget]);
+
+  if (!markerMap[markerName]) {
+    markerMap[markerName] = new WeakMap();
+  }
+
+  const markerCounter = markerMap[markerName];
+
+  /** @type {Element[]} */
+  const hiddenNodes = [];
+
+  /** @type {Set<Node>} */
+  const elementsToKeep = new Set();
+
+  /** @type {Set<Node>} */
+  const elementsToStop = new Set(targets);
+
+  /**
+   * @param {?Node} el
+   */
+  const keep = (el) => {
+    if (!el || elementsToKeep.has(el)) {
+      return;
+    }
+
+    elementsToKeep.add(el);
+    keep(el.parentNode);
+  };
+
+  targets.forEach(keep);
+
+  /**
+   * @param {?Node} el
+   */
+  const deep = (parent) => {
+    if (!parent || elementsToStop.has(parent)) {
+      return;
+    }
+
+    [...parent.children].forEach((node) => {
+      // Skip elements that don't need to be hidden
+      if (['template', 'script', 'style'].includes(node.localName)) {
+        return;
+      }
+
+      if (elementsToKeep.has(node)) {
+        deep(node);
+      } else {
+        const attr = node.getAttribute(controlAttribute);
+        const alreadyHidden = attr !== null && attr !== 'false';
+        const counterValue = (counterMap.get(node) || 0) + 1;
+        const markerValue = (markerCounter.get(node) || 0) + 1;
+
+        counterMap.set(node, counterValue);
+        markerCounter.set(node, markerValue);
+        hiddenNodes.push(node);
+
+        if (counterValue === 1 && alreadyHidden) {
+          uncontrolledNodes.set(node, true);
+        }
+
+        if (markerValue === 1) {
+          node.setAttribute(markerName, 'true');
+        }
+
+        if (!alreadyHidden) {
+          node.setAttribute(controlAttribute, 'true');
+        }
+      }
+    });
+  };
+
+  deep(parentNode);
+
+  elementsToKeep.clear();
+
+  lockCount += 1;
+
+  return () => {
+    hiddenNodes.forEach((node) => {
+      const counterValue = counterMap.get(node) - 1;
+      const markerValue = markerCounter.get(node) - 1;
+
+      counterMap.set(node, counterValue);
+      markerCounter.set(node, markerValue);
+
+      if (!counterValue) {
+        if (uncontrolledNodes.has(node)) {
+          uncontrolledNodes.delete(node);
+        } else {
+          node.removeAttribute(controlAttribute);
+        }
+      }
+
+      if (!markerValue) {
+        node.removeAttribute(markerName);
+      }
+    });
+
+    lockCount -= 1;
+
+    if (!lockCount) {
+      // clear
+      counterMap = new WeakMap();
+      counterMap = new WeakMap();
+      uncontrolledNodes = new WeakMap();
+      markerMap = {};
+    }
+  };
+};
+
+/**
+ * Marks everything except given node(or nodes) as aria-hidden
+ * @param {Element | Element[]} originalTarget - elements to keep on the page
+ * @param {HTMLElement} [parentNode] - top element, defaults to document.body
+ * @param {String} [markerName] - a special attribute to mark every node
+ * @return {Function} undo command
+ */
+export const hideOthers = (originalTarget, parentNode = document.body, markerName = 'data-aria-hidden') => {
+  const targets = Array.from(Array.isArray(originalTarget) ? originalTarget : [originalTarget]);
+
+  if (parentNode) {
+    // We should not hide ariaLive elements - https://github.com/theKashey/aria-hidden/issues/10
+    targets.push(...Array.from(parentNode.querySelectorAll('[aria-live]')));
+  }
+
+  return applyAttributeToOthers(targets, parentNode, markerName, 'aria-hidden');
+};
+
+/**
+ * Marks everything except given node(or nodes) as inert
+ * @param {Element | Element[]} originalTarget - elements to keep on the page
+ * @param {HTMLElement} [parentNode] - top element, defaults to document.body
+ * @param {String} [markerName] - a special attribute to mark every node
+ * @return {Function} undo command
+ */
+export const inertOthers = (originalTarget, parentNode = document.body, markerName = 'data-inert-ed') => {
+  return applyAttributeToOthers(originalTarget, parentNode, markerName, 'inert');
+};
+
+/**
+ * @return if current browser supports inert
+ */
+export const supportsInert = 'inert' in HTMLElement.prototype;
+
+/**
+ * Automatic function to "suppress" DOM elements - _hide_ or _inert_ in the best possible way
+ * @param {Element | Element[]} originalTarget - elements to keep on the page
+ * @param {HTMLElement} [parentNode] - top element, defaults to document.body
+ * @param {String} [markerName] - a special attribute to mark every node
+ * @return {Function} undo command
+ */
+export const suppressOthers = (originalTarget, parentNode, markerName) =>
+  (supportsInert ? inertOthers : hideOthers)(originalTarget, parentNode, markerName);

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

@@ -0,0 +1,34 @@
+/**
+ * @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 handling modal state on the elements with `dialog` and `alertdialog` role.
+ * See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal
+ */
+export class AriaModalController implements ReactiveController {
+  /**
+   * The controller host element.
+   */
+  host: HTMLElement;
+
+  constructor(node: HTMLElement);
+
+  /**
+   * Make the controller host element modal by trapping focus inside it and hiding
+   * other elements from screen readers using `aria-hidden="true"` appropriately.
+   *
+   * The method name is chosen to align with the one provided by native `<dialog>`:
+   * https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal
+   */
+  showModal(): void;
+
+  /**
+   * Exit modal state: release focus and remove `aria-hidden` from other elements
+   * unless there are any other underlying elements that are also shown as modal.
+   */
+  close(): void;
+}

package/src/aria-modal-controller.js

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { hideOthers } from './aria-hidden.js';
+
+/**
+ * A controller for handling modal state on the elements with `dialog` and `alertdialog` role.
+ * See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal
+ *
+ * Note, the actual `role` and `aria-modal` attributes are supposed to be handled by the
+ * consumer web component. This is done in to ensure the controller only does one thing.
+ */
+export class AriaModalController {
+  /**
+   * @param {HTMLElement} host
+   */
+  constructor(host) {
+    /**
+     * The controller host element.
+     *
+     * @type {HTMLElement}
+     */
+    this.host = host;
+  }
+
+  /**
+   * Make the controller host modal by hiding other elements from screen readers
+   * using `aria-hidden` attribute (can be replaced with `inert` in the future).
+   *
+   * The method name is chosen to align with the one provided by native `<dialog>`:
+   * https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal
+   */
+  showModal() {
+    this.__showOthers = hideOthers(this.host);
+  }
+
+  /**
+   * Remove `aria-hidden` from other elements unless there are any other
+   * controller hosts on the page activated by using `showModal()` call.
+   */
+  close() {
+    if (this.__showOthers) {
+      this.__showOthers();
+      this.__showOthers = null;
+    }
+  }
+}

package/src/delegate-focus-mixin.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @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';
+import type { DisabledMixinClass } from './disabled-mixin.js';
+import type { FocusMixinClass } from './focus-mixin.js';
+import type { TabindexMixinClass } from './tabindex-mixin.js';
+
+/**
+ * A mixin to forward focus to an element in the light DOM.
+ */
+export declare function DelegateFocusMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<DelegateFocusMixinClass> &
+  Constructor<DisabledMixinClass> &
+  Constructor<FocusMixinClass> &
+  Constructor<TabindexMixinClass> &
+  T;
+
+export declare class DelegateFocusMixinClass {
+  /**
+   * Specify that this control should have input focus when the page loads.
+   */
+  autofocus: boolean;
+
+  /**
+   * A reference to the focusable element controlled by the mixin.
+   * It can be an input, textarea, button or any element with tabindex > -1.
+   *
+   * Any component implementing this mixin is expected to provide it
+   * by using `this._setFocusElement(input)` Polymer API.
+   */
+  readonly focusElement: HTMLElement | null | undefined;
+
+  protected _addFocusListeners(element: HTMLElement): void;
+
+  protected _removeFocusListeners(element: HTMLElement): void;
+
+  protected _focusElementChanged(element: HTMLElement, oldElement: HTMLElement): void;
+
+  protected _onBlur(event: FocusEvent): void;
+
+  protected _onFocus(event: FocusEvent): void;
+
+  protected _setFocusElement(element: HTMLElement): void;
+}

package/src/delegate-focus-mixin.js

@@ -0,0 +1,228 @@
+/**
+ * @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 { FocusMixin } from './focus-mixin.js';
+import { TabindexMixin } from './tabindex-mixin.js';
+
+/**
+ * A mixin to forward focus to an element in the light DOM.
+ *
+ * @polymerMixin
+ * @mixes FocusMixin
+ * @mixes TabindexMixin
+ */
+export const DelegateFocusMixin = dedupingMixin(
+  (superclass) =>
+    class DelegateFocusMixinClass extends FocusMixin(TabindexMixin(superclass)) {
+      static get properties() {
+        return {
+          /**
+           * Specify that this control should have input focus when the page loads.
+           */
+          autofocus: {
+            type: Boolean,
+          },
+
+          /**
+           * A reference to the focusable element controlled by the mixin.
+           * It can be an input, textarea, button or any element with tabindex > -1.
+           *
+           * Any component implementing this mixin is expected to provide it
+           * by using `this._setFocusElement(input)` Polymer API.
+           *
+           * Toggling `tabindex` attribute on the host element propagates its value to `focusElement`.
+           *
+           * @protected
+           * @type {!HTMLElement}
+           */
+          focusElement: {
+            type: Object,
+            readOnly: true,
+            observer: '_focusElementChanged',
+          },
+
+          /**
+           * Override the property from `TabIndexMixin`
+           * to ensure the `tabindex` attribute of the focus element
+           * will be restored to `0` after re-enabling the element.
+           *
+           * @protected
+           * @override
+           */
+          _lastTabIndex: {
+            value: 0,
+          },
+        };
+      }
+
+      constructor() {
+        super();
+
+        this._boundOnBlur = this._onBlur.bind(this);
+        this._boundOnFocus = this._onFocus.bind(this);
+      }
+
+      /** @protected */
+      ready() {
+        super.ready();
+
+        if (this.autofocus && !this.disabled) {
+          requestAnimationFrame(() => {
+            this.focus();
+            this.setAttribute('focus-ring', '');
+          });
+        }
+      }
+
+      /**
+       * @protected
+       * @override
+       */
+      focus() {
+        if (!this.focusElement || this.disabled) {
+          return;
+        }
+
+        this.focusElement.focus();
+        this._setFocused(true);
+      }
+
+      /**
+       * @protected
+       * @override
+       */
+      blur() {
+        if (!this.focusElement) {
+          return;
+        }
+        this.focusElement.blur();
+        this._setFocused(false);
+      }
+
+      /**
+       * @protected
+       * @override
+       */
+      click() {
+        if (this.focusElement && !this.disabled) {
+          this.focusElement.click();
+        }
+      }
+
+      /** @protected */
+      _focusElementChanged(element, oldElement) {
+        if (element) {
+          element.disabled = this.disabled;
+          this._addFocusListeners(element);
+          this.__forwardTabIndex(this.tabindex);
+        } else if (oldElement) {
+          this._removeFocusListeners(oldElement);
+        }
+      }
+
+      /**
+       * @param {HTMLElement} element
+       * @protected
+       */
+      _addFocusListeners(element) {
+        element.addEventListener('blur', this._boundOnBlur);
+        element.addEventListener('focus', this._boundOnFocus);
+      }
+
+      /**
+       * @param {HTMLElement} element
+       * @protected
+       */
+      _removeFocusListeners(element) {
+        element.removeEventListener('blur', this._boundOnBlur);
+        element.removeEventListener('focus', this._boundOnFocus);
+      }
+
+      /**
+       * Focus event does not bubble, so we dispatch it manually
+       * on the host element to support adding focus listeners
+       * when the focusable element is placed in light DOM.
+       * @param {FocusEvent} event
+       * @protected
+       */
+      _onFocus(event) {
+        event.stopPropagation();
+        this.dispatchEvent(new Event('focus'));
+      }
+
+      /**
+       * Blur event does not bubble, so we dispatch it manually
+       * on the host element to support adding blur listeners
+       * when the focusable element is placed in light DOM.
+       * @param {FocusEvent} event
+       * @protected
+       */
+      _onBlur(event) {
+        event.stopPropagation();
+        this.dispatchEvent(new Event('blur'));
+      }
+
+      /**
+       * @param {Event} event
+       * @return {boolean}
+       * @protected
+       * @override
+       */
+      _shouldSetFocus(event) {
+        return event.target === this.focusElement;
+      }
+
+      /**
+       * @param {boolean} disabled
+       * @param {boolean} oldDisabled
+       * @protected
+       * @override
+       */
+      _disabledChanged(disabled, oldDisabled) {
+        super._disabledChanged(disabled, oldDisabled);
+
+        if (this.focusElement) {
+          this.focusElement.disabled = disabled;
+        }
+
+        if (disabled) {
+          this.blur();
+        }
+      }
+
+      /**
+       * Override an observer from `TabindexMixin`.
+       * Do not call super to remove tabindex attribute
+       * from the host after it has been forwarded.
+       * @param {string} tabindex
+       * @protected
+       * @override
+       */
+      _tabindexChanged(tabindex) {
+        this.__forwardTabIndex(tabindex);
+      }
+
+      /** @private */
+      __forwardTabIndex(tabindex) {
+        if (tabindex !== undefined && this.focusElement) {
+          this.focusElement.tabIndex = tabindex;
+
+          // Preserve tabindex="-1" on the host element
+          if (tabindex !== -1) {
+            this.tabindex = undefined;
+          }
+        }
+
+        if (this.disabled && tabindex) {
+          // If tabindex attribute was changed while component was disabled
+          if (tabindex !== -1) {
+            this._lastTabIndex = tabindex;
+          }
+          this.tabindex = undefined;
+        }
+      }
+    },
+);

package/src/disabled-mixin.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @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 provide disabled property for field components.
+ */
+export declare function DisabledMixin<T extends Constructor<HTMLElement>>(base: T): Constructor<DisabledMixinClass> & T;
+
+export declare class DisabledMixinClass {
+  /**
+   * If true, the user cannot interact with this element.
+   */
+  disabled: boolean;
+
+  protected _disabledChanged(disabled: boolean, oldDisabled: boolean): void;
+}

package/src/disabled-mixin.js

@@ -0,0 +1,62 @@
+/**
+ * @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';
+
+/**
+ * A mixin to provide disabled property for field components.
+ *
+ * @polymerMixin
+ */
+export const DisabledMixin = dedupingMixin(
+  (superclass) =>
+    class DisabledMixinClass extends superclass {
+      static get properties() {
+        return {
+          /**
+           * If true, the user cannot interact with this element.
+           */
+          disabled: {
+            type: Boolean,
+            value: false,
+            observer: '_disabledChanged',
+            reflectToAttribute: true,
+          },
+        };
+      }
+
+      /**
+       * @param {boolean} disabled
+       * @protected
+       */
+      _disabledChanged(disabled) {
+        this._setAriaDisabled(disabled);
+      }
+
+      /**
+       * @param {boolean} disabled
+       * @protected
+       */
+      _setAriaDisabled(disabled) {
+        if (disabled) {
+          this.setAttribute('aria-disabled', 'true');
+        } else {
+          this.removeAttribute('aria-disabled');
+        }
+      }
+
+      /**
+       * Overrides the default element `click` method in order to prevent
+       * firing the `click` event when the element is disabled.
+       * @protected
+       * @override
+       */
+      click() {
+        if (!this.disabled) {
+          super.click();
+        }
+      }
+    },
+);