@vaadin/a11y-base 24.1.0-alpha1

package/src/focus-utils.js

@@ -0,0 +1,260 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+// We consider the keyboard to be active if the window has received a keydown
+// event since the last mousedown event.
+let keyboardActive = false;
+
+// Listen for top-level keydown and mousedown events.
+// Use capture phase so we detect events even if they're handled.
+window.addEventListener(
+  'keydown',
+  () => {
+    keyboardActive = true;
+  },
+  { capture: true },
+);
+
+window.addEventListener(
+  'mousedown',
+  () => {
+    keyboardActive = false;
+  },
+  { capture: true },
+);
+
+/**
+ * Returns true if the window has received a keydown
+ * event since the last mousedown event.
+ *
+ * @return {boolean}
+ */
+export function isKeyboardActive() {
+  return keyboardActive;
+}
+
+/**
+ * Returns true if the element is hidden directly with `display: none` or `visibility: hidden`,
+ * false otherwise.
+ *
+ * The method doesn't traverse the element's ancestors, it only checks for the CSS properties
+ * set directly to or inherited by the element.
+ *
+ * @param {HTMLElement} element
+ * @return {boolean}
+ */
+function isElementHiddenDirectly(element) {
+  // Check inline style first to save a re-flow.
+  const style = element.style;
+  if (style.visibility === 'hidden' || style.display === 'none') {
+    return true;
+  }
+
+  const computedStyle = window.getComputedStyle(element);
+  if (computedStyle.visibility === 'hidden' || computedStyle.display === 'none') {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Returns if element `a` has lower tab order compared to element `b`
+ * (both elements are assumed to be focusable and tabbable).
+ * Elements with tabindex = 0 have lower tab order compared to elements
+ * with tabindex > 0.
+ * If both have same tabindex, it returns false.
+ *
+ * @param {HTMLElement} a
+ * @param {HTMLElement} b
+ * @return {boolean}
+ */
+function hasLowerTabOrder(a, b) {
+  // Normalize tabIndexes
+  // e.g. in Firefox `<div contenteditable>` has `tabIndex = -1`
+  const ati = Math.max(a.tabIndex, 0);
+  const bti = Math.max(b.tabIndex, 0);
+  return ati === 0 || bti === 0 ? bti > ati : ati > bti;
+}
+
+/**
+ * Merge sort iterator, merges the two arrays into one, sorted by tabindex.
+ *
+ * @param {HTMLElement[]} left
+ * @param {HTMLElement[]} right
+ * @return {HTMLElement[]}
+ */
+function mergeSortByTabIndex(left, right) {
+  const result = [];
+  while (left.length > 0 && right.length > 0) {
+    if (hasLowerTabOrder(left[0], right[0])) {
+      result.push(right.shift());
+    } else {
+      result.push(left.shift());
+    }
+  }
+
+  return result.concat(left, right);
+}
+
+/**
+ * Sorts an array of elements by tabindex. Returns a new array.
+ *
+ * @param {HTMLElement[]} elements
+ * @return {HTMLElement[]}
+ */
+function sortElementsByTabIndex(elements) {
+  // Implement a merge sort as Array.prototype.sort does a non-stable sort
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort
+  const len = elements.length;
+  if (len < 2) {
+    return elements;
+  }
+  const pivot = Math.ceil(len / 2);
+  const left = sortElementsByTabIndex(elements.slice(0, pivot));
+  const right = sortElementsByTabIndex(elements.slice(pivot));
+
+  return mergeSortByTabIndex(left, right);
+}
+
+/**
+ * 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`.
+ *
+ * @param {HTMLElement} element
+ * @return {boolean}
+ */
+export function isElementHidden(element) {
+  // `offsetParent` is `null` when the element itself
+  // or one of its ancestors is hidden with `display: none`.
+  // https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetParent
+  if (element.offsetParent === null) {
+    return true;
+  }
+
+  return isElementHiddenDirectly(element);
+}
+
+/**
+ * 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
+ *
+ * @param {HTMLElement} element
+ * @return {boolean}
+ */
+export function isElementFocusable(element) {
+  // The element cannot be focused if its `tabindex` attribute is set to `-1`.
+  if (element.matches('[tabindex="-1"]')) {
+    return false;
+  }
+
+  // Elements that cannot be focused if they have a `disabled` attribute.
+  if (element.matches('input, select, textarea, button, object')) {
+    return element.matches(':not([disabled])');
+  }
+
+  // Elements that can be focused even if they have a `disabled` attribute.
+  return element.matches('a[href], area[href], iframe, [tabindex], [contentEditable]');
+}
+
+/**
+ * Returns true if the element is focused, false otherwise.
+ *
+ * @param {HTMLElement} element
+ * @return {boolean}
+ */
+export function isElementFocused(element) {
+  return element.getRootNode().activeElement === element;
+}
+
+/**
+ * Returns the normalized element tabindex. If not focusable, returns -1.
+ * It checks for the attribute "tabindex" instead of the element property
+ * `tabIndex` since browsers assign different values to it.
+ * e.g. in Firefox `<div contenteditable>` has `tabIndex = -1`
+ *
+ * @param {HTMLElement} element
+ * @return {number}
+ */
+function normalizeTabIndex(element) {
+  if (!isElementFocusable(element)) {
+    return -1;
+  }
+
+  const tabIndex = element.getAttribute('tabindex') || 0;
+  return Number(tabIndex);
+}
+
+/**
+ * Searches for nodes that are tabbable and adds them to the `result` array.
+ * Returns if the `result` array needs to be sorted by tabindex.
+ *
+ * @param {Node} node The starting point for the search; added to `result` if tabbable.
+ * @param {HTMLElement[]} result
+ * @return {boolean}
+ * @private
+ */
+function collectFocusableNodes(node, result) {
+  if (node.nodeType !== Node.ELEMENT_NODE || isElementHiddenDirectly(node)) {
+    // Don't traverse children if the node is not an HTML element or not visible.
+    return false;
+  }
+
+  const element = /** @type {HTMLElement} */ (node);
+  const tabIndex = normalizeTabIndex(element);
+  let needsSort = tabIndex > 0;
+  if (tabIndex >= 0) {
+    result.push(element);
+  }
+
+  let children = [];
+  if (element.localName === 'slot') {
+    children = element.assignedNodes({ flatten: true });
+  } else {
+    // Use shadow root if possible, will check for distributed nodes.
+    children = (element.shadowRoot || element).children;
+  }
+  [...children].forEach((child) => {
+    // Ensure method is always invoked to collect focusable children.
+    needsSort = collectFocusableNodes(child, result) || needsSort;
+  });
+  return needsSort;
+}
+
+/**
+ * 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.
+ *
+ * @param {HTMLElement} element
+ * @return {HTMLElement[]}
+ */
+export function getFocusableElements(element) {
+  const focusableElements = [];
+  const needsSortByTabIndex = collectFocusableNodes(element, focusableElements);
+  // If there is at least one element with tabindex > 0,
+  // we need to sort the final array by tabindex.
+  if (needsSortByTabIndex) {
+    return sortElementsByTabIndex(focusableElements);
+  }
+  return focusableElements;
+}

package/src/keyboard-direction-mixin.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright (c) 2022 - 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 { KeyboardMixinClass } from './keyboard-mixin.js';
+
+/**
+ * A mixin for navigating items with keyboard.
+ */
+export declare function KeyboardDirectionMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<KeyboardDirectionMixinClass> & Constructor<KeyboardMixinClass> & T;
+
+export declare class KeyboardDirectionMixinClass {
+  protected readonly focused: Element | null;
+
+  protected readonly _vertical: boolean;
+
+  /**
+   * Returns index of the next item that satisfies the given condition,
+   * based on the index of the current item and a numeric increment.
+   */
+  protected _getAvailableIndex(
+    items: Element[],
+    index: number,
+    increment: number,
+    condition: (item: Element) => boolean,
+  ): number;
+
+  /**
+   * Focus the item at given index. Override this method to add custom logic.
+   */
+  protected _focus(index: number, navigating: boolean): void;
+
+  /**
+   * Focus the given item. Override this method to add custom logic.
+   */
+  protected _focusItem(item: Element, navigating: boolean): void;
+}

package/src/keyboard-direction-mixin.js

@@ -0,0 +1,192 @@
+/**
+ * @license
+ * Copyright (c) 2022 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { isElementFocused, isElementHidden } from './focus-utils.js';
+import { KeyboardMixin } from './keyboard-mixin.js';
+
+/**
+ * A mixin for navigating items with keyboard.
+ *
+ * @polymerMixin
+ * @mixes KeyboardMixin
+ */
+export const KeyboardDirectionMixin = (superclass) =>
+  class KeyboardDirectionMixinClass extends KeyboardMixin(superclass) {
+    /**
+     * @return {Element | null}
+     * @protected
+     */
+    get focused() {
+      return (this._getItems() || []).find(isElementFocused);
+    }
+
+    /**
+     * @return {boolean}
+     * @protected
+     */
+    get _vertical() {
+      return true;
+    }
+
+    /** @protected */
+    focus() {
+      const items = this._getItems();
+      if (Array.isArray(items)) {
+        const idx = this._getAvailableIndex(items, 0, null, (item) => !isElementHidden(item));
+        if (idx >= 0) {
+          items[idx].focus();
+        }
+      }
+    }
+
+    /**
+     * Get the list of items participating in keyboard navigation.
+     * By default, it treats all the light DOM children as items.
+     * Override this method to provide custom list of elements.
+     *
+     * @return {Element[]}
+     * @protected
+     */
+    _getItems() {
+      return Array.from(this.children);
+    }
+
+    /**
+     * Override an event listener from `KeyboardMixin`.
+     *
+     * @param {!KeyboardEvent} event
+     * @protected
+     * @override
+     */
+    _onKeyDown(event) {
+      super._onKeyDown(event);
+
+      if (event.metaKey || event.ctrlKey) {
+        return;
+      }
+
+      const { key } = event;
+      const items = this._getItems() || [];
+      const currentIdx = items.indexOf(this.focused);
+
+      let idx;
+      let increment;
+
+      const isRTL = !this._vertical && this.getAttribute('dir') === 'rtl';
+      const dirIncrement = isRTL ? -1 : 1;
+
+      if (this.__isPrevKey(key)) {
+        increment = -dirIncrement;
+        idx = currentIdx - dirIncrement;
+      } else if (this.__isNextKey(key)) {
+        increment = dirIncrement;
+        idx = currentIdx + dirIncrement;
+      } else if (key === 'Home') {
+        increment = 1;
+        idx = 0;
+      } else if (key === 'End') {
+        increment = -1;
+        idx = items.length - 1;
+      }
+
+      idx = this._getAvailableIndex(items, idx, increment, (item) => !isElementHidden(item));
+
+      if (idx >= 0) {
+        event.preventDefault();
+        this._focus(idx, true);
+      }
+    }
+
+    /**
+     * @param {string} key
+     * @return {boolean}
+     * @private
+     */
+    __isPrevKey(key) {
+      return this._vertical ? key === 'ArrowUp' : key === 'ArrowLeft';
+    }
+
+    /**
+     * @param {string} key
+     * @return {boolean}
+     * @private
+     */
+    __isNextKey(key) {
+      return this._vertical ? key === 'ArrowDown' : key === 'ArrowRight';
+    }
+
+    /**
+     * Focus the item at given index. Override this method to add custom logic.
+     *
+     * @param {number} index
+     * @param {boolean} navigating
+     * @protected
+     */
+    _focus(index, navigating = false) {
+      const items = this._getItems();
+
+      this._focusItem(items[index], navigating);
+    }
+
+    /**
+     * Focus the given item. Override this method to add custom logic.
+     *
+     * @param {Element} item
+     * @param {boolean} navigating
+     * @protected
+     */
+    _focusItem(item) {
+      if (item) {
+        item.focus();
+
+        // Generally, the items are expected to implement `FocusMixin`
+        // that would set this attribute based on the `keydown` event.
+        // We set it manually to handle programmatic focus() calls.
+        item.setAttribute('focus-ring', '');
+      }
+    }
+
+    /**
+     * Returns index of the next item that satisfies the given condition,
+     * based on the index of the current item and a numeric increment.
+     *
+     * @param {Element[]} items - array of items to iterate over
+     * @param {number} index - index of the current item
+     * @param {number} increment - numeric increment, can be either 1 or -1
+     * @param {Function} condition - function used to check the item
+     * @return {number}
+     * @protected
+     */
+    _getAvailableIndex(items, index, increment, condition) {
+      const totalItems = items.length;
+      let idx = index;
+      for (let i = 0; typeof idx === 'number' && i < totalItems; i += 1, idx += increment || 1) {
+        if (idx < 0) {
+          idx = totalItems - 1;
+        } else if (idx >= totalItems) {
+          idx = 0;
+        }
+
+        const item = items[idx];
+
+        if (!item.hasAttribute('disabled') && this.__isMatchingItem(item, condition)) {
+          return idx;
+        }
+      }
+      return -1;
+    }
+
+    /**
+     * Returns true if the item matches condition.
+     *
+     * @param {Element} item - item to check
+     * @param {Function} condition - function used to check the item
+     * @return {number}
+     * @private
+     */
+    __isMatchingItem(item, condition) {
+      return typeof condition === 'function' ? condition(item) : true;
+    }
+  };

package/src/keyboard-mixin.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @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 that manages keyboard handling.
+ * The mixin subscribes to the keyboard events while an actual implementation
+ * for the event handlers is left to the client (a component or another mixin).
+ */
+export declare function KeyboardMixin<T extends Constructor<HTMLElement>>(base: T): Constructor<KeyboardMixinClass> & T;
+
+export declare class KeyboardMixinClass {
+  /**
+   * A handler for the "Enter" key. By default, it does nothing.
+   * Override the method to implement your own behavior.
+   */
+  protected _onEnter(event: KeyboardEvent): void;
+
+  /**
+   * A handler for the "Escape" key. By default, it does nothing.
+   * Override the method to implement your own behavior.
+   */
+  protected _onEscape(event: KeyboardEvent): void;
+
+  /**
+   * A handler for the `keydown` event. By default, it calls
+   * separate methods for handling "Enter" and "Escape" keys.
+   * Override the method to implement your own behavior.
+   */
+  protected _onKeyDown(event: KeyboardEvent): void;
+
+  /**
+   * A handler for the `keyup` event. By default, it does nothing.
+   * Override the method to implement your own behavior.
+   */
+  protected _onKeyUp(event: KeyboardEvent): void;
+}

package/src/keyboard-mixin.js

@@ -0,0 +1,85 @@
+/**
+ * @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 that manages keyboard handling.
+ * The mixin subscribes to the keyboard events while an actual implementation
+ * for the event handlers is left to the client (a component or another mixin).
+ *
+ * @polymerMixin
+ */
+export const KeyboardMixin = dedupingMixin(
+  (superclass) =>
+    class KeyboardMixinClass extends superclass {
+      /** @protected */
+      ready() {
+        super.ready();
+
+        this.addEventListener('keydown', (event) => {
+          this._onKeyDown(event);
+        });
+
+        this.addEventListener('keyup', (event) => {
+          this._onKeyUp(event);
+        });
+      }
+
+      /**
+       * A handler for the `keydown` event. By default, it calls
+       * separate methods for handling "Enter" and "Escape" keys.
+       * Override the method to implement your own behavior.
+       *
+       * @param {KeyboardEvent} event
+       * @protected
+       */
+      _onKeyDown(event) {
+        switch (event.key) {
+          case 'Enter':
+            this._onEnter(event);
+            break;
+          case 'Escape':
+            this._onEscape(event);
+            break;
+          default:
+            break;
+        }
+      }
+
+      /**
+       * A handler for the `keyup` event. By default, it does nothing.
+       * Override the method to implement your own behavior.
+       *
+       * @param {KeyboardEvent} _event
+       * @protected
+       */
+      _onKeyUp(_event) {
+        // To be implemented.
+      }
+
+      /**
+       * A handler for the "Enter" key. By default, it does nothing.
+       * Override the method to implement your own behavior.
+       *
+       * @param {KeyboardEvent} _event
+       * @protected
+       */
+      _onEnter(_event) {
+        // To be implemented.
+      }
+
+      /**
+       * A handler for the "Escape" key. By default, it does nothing.
+       * Override the method to implement your own behavior.
+       *
+       * @param {KeyboardEvent} _event
+       * @protected
+       */
+      _onEscape(_event) {
+        // To be implemented.
+      }
+    },
+);

package/src/list-mixin.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 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 { KeyboardDirectionMixinClass } from './keyboard-direction-mixin.js';
+import type { KeyboardMixinClass } from './keyboard-mixin.js';
+
+/**
+ * A mixin for list elements, facilitating navigation and selection of items.
+ */
+export declare function ListMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<KeyboardDirectionMixinClass> & Constructor<KeyboardMixinClass> & Constructor<ListMixinClass> & T;
+
+export declare class ListMixinClass {
+  /**
+   * Used for mixin detection because `instanceof` does not work with mixins.
+   */
+  _hasVaadinListMixin: boolean;
+
+  /**
+   * If true, the user cannot interact with this element.
+   * When the element is disabled, the selected item is
+   * not updated when `selected` property is changed.
+   */
+  disabled: boolean;
+
+  /**
+   * The index of the item selected in the items array.
+   * Note: Not updated when used in `multiple` selection mode.
+   */
+  selected: number | null | undefined;
+
+  /**
+   * Define how items are disposed in the dom.
+   * Possible values are: `horizontal|vertical`.
+   * It also changes navigation keys from left/right to up/down.
+   */
+  orientation: 'horizontal' | 'vertical';
+
+  /**
+   * The list of items from which a selection can be made.
+   * It is populated from the elements passed to the light DOM,
+   * and updated dynamically when adding or removing items.
+   *
+   * The item elements must implement `Vaadin.ItemMixin`.
+   *
+   * Note: unlike `<vaadin-combo-box>`, this property is read-only,
+   * so if you want to provide items by iterating array of data,
+   * you have to use `dom-repeat` and place it to the light DOM.
+   */
+  readonly items: Element[] | undefined;
+
+  protected readonly _scrollerElement: HTMLElement;
+}