@vaadin/component-base 22.0.0-rc1 → 23.0.0-alpha2

package/index.d.ts

@@ -4,6 +4,8 @@ export { DirMixin } from './src/dir-mixin.js';
 export { DisabledMixin } from './src/disabled-mixin.js';
 export { ElementMixin } from './src/element-mixin.js';
 export { FocusMixin } from './src/focus-mixin.js';
+export { FocusTrapController } from './src/focus-trap-controller.js';
 export { KeyboardMixin } from './src/keyboard-mixin.js';
+export { SlotController } from './src/slot-controller.js';
 export { SlotMixin } from './src/slot-mixin.js';
 export { TabindexMixin } from './src/tabindex-mixin.js';

package/index.js

@@ -4,6 +4,8 @@ export { DirMixin } from './src/dir-mixin.js';
 export { DisabledMixin } from './src/disabled-mixin.js';
 export { ElementMixin } from './src/element-mixin.js';
 export { FocusMixin } from './src/focus-mixin.js';
+export { FocusTrapController } from './src/focus-trap-controller.js';
 export { KeyboardMixin } from './src/keyboard-mixin.js';
+export { SlotController } from './src/slot-controller.js';
 export { SlotMixin } from './src/slot-mixin.js';
 export { TabindexMixin } from './src/tabindex-mixin.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/component-base",
-  "version": "22.0.0-rc1",
+  "version": "23.0.0-alpha2",
   "publishConfig": {
     "access": "public"
   },
@@ -41,5 +41,5 @@
     "@vaadin/testing-helpers": "^0.3.2",
     "sinon": "^9.2.4"
   },
-  "gitHead": "7b6f44bcd2c0fd415028ace666feeb0fedb1d540"
+  "gitHead": "070f586dead02ca41b66717820c647f48bf1665f"
 }

package/src/active-mixin.js

@@ -3,7 +3,7 @@
  * Copyright (c) 2021 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { GestureEventListeners } from '@polymer/polymer/lib/mixins/gesture-event-listeners.js';
+import { addListener } from '@vaadin/component-base/src/gestures.js';
 import { DisabledMixin } from './disabled-mixin.js';
 import { KeyboardMixin } from './keyboard-mixin.js';
 
@@ -19,7 +19,7 @@ import { KeyboardMixin } from './keyboard-mixin.js';
  * @polymerMixin
  */
 export const ActiveMixin = (superclass) =>
-  class ActiveMixinClass extends DisabledMixin(GestureEventListeners(KeyboardMixin(superclass))) {
+  class ActiveMixinClass extends DisabledMixin(KeyboardMixin(superclass)) {
     /**
      * An array of activation keys.
      *
@@ -37,13 +37,13 @@ export const ActiveMixin = (superclass) =>
     ready() {
       super.ready();
 
-      this._addEventListenerToNode(this, 'down', (event) => {
+      addListener(this, 'down', (event) => {
         if (this._shouldSetActive(event)) {
           this._setActive(true);
         }
       });
 
-      this._addEventListenerToNode(this, 'up', () => {
+      addListener(this, 'up', () => {
         this._setActive(false);
       });
     }

package/src/async.js

@@ -23,17 +23,17 @@
 // Microtask implemented using Mutation Observer
 let microtaskCurrHandle = 0;
 let microtaskLastHandle = 0;
-let microtaskCallbacks = [];
+const microtaskCallbacks = [];
 let microtaskNodeContent = 0;
 let microtaskScheduled = false;
-let microtaskNode = document.createTextNode('');
+const microtaskNode = document.createTextNode('');
 new window.MutationObserver(microtaskFlush).observe(microtaskNode, { characterData: true });
 
 function microtaskFlush() {
   microtaskScheduled = false;
   const len = microtaskCallbacks.length;
   for (let i = 0; i < len; i++) {
-    let cb = microtaskCallbacks[i];
+    const cb = microtaskCallbacks[i];
     if (cb) {
       try {
         cb();

package/src/debounce.js

@@ -17,6 +17,7 @@ export class Debouncer {
     this._callback = null;
     this._timer = null;
   }
+
   /**
    * Sets the scheduler; that is, a module with the Async interface,
    * a callback and optional arguments to be passed to the run function
@@ -35,6 +36,7 @@ export class Debouncer {
       this._callback();
     });
   }
+
   /**
    * Cancels an active debouncer and returns a reference to itself.
    *
@@ -50,6 +52,7 @@ export class Debouncer {
       debouncerQueue.delete(this);
     }
   }
+
   /**
    * Cancels a debouncer's async callback.
    *
@@ -61,6 +64,7 @@ export class Debouncer {
       this._timer = null;
     }
   }
+
   /**
    * Flushes an active debouncer and returns a reference to itself.
    *
@@ -72,6 +76,7 @@ export class Debouncer {
       this._callback();
     }
   }
+
   /**
    * Returns true if the debouncer is active.
    *
@@ -80,6 +85,7 @@ export class Debouncer {
   isActive() {
     return this._timer != null;
   }
+
   /**
    * Creates a debouncer if no debouncer is passed as a parameter
    * or it cancels an active debouncer otherwise. The following
@@ -135,16 +141,16 @@ let debouncerQueue = new Set();
  * @param {!Debouncer} debouncer Debouncer to enqueue
  * @return {void}
  */
-export const enqueueDebouncer = function (debouncer) {
+export function enqueueDebouncer(debouncer) {
   debouncerQueue.add(debouncer);
-};
+}
 
 /**
  * Flushes any enqueued debouncers
  *
  * @return {boolean} Returns whether any debouncers were flushed
  */
-export const flushDebouncers = function () {
+export function flushDebouncers() {
   const didFlush = Boolean(debouncerQueue.size);
   // If new debouncers are added while flushing, Set.forEach will ensure
   // newly added ones are also flushed
@@ -158,7 +164,7 @@ export const flushDebouncers = function () {
     }
   });
   return didFlush;
-};
+}
 
 export const flush = () => {
   let debouncers;

package/src/dir-helper.js

@@ -57,8 +57,9 @@ class DirHelper {
         return element.scrollWidth - element.clientWidth + scrollLeft;
       case 'reverse':
         return element.scrollWidth - element.clientWidth - scrollLeft;
+      default:
+        return scrollLeft;
     }
-    return scrollLeft;
   }
 
   /**

package/src/dir-mixin.js

@@ -9,29 +9,29 @@ import { DirHelper } from './dir-helper.js';
  * Array of Vaadin custom element classes that have been subscribed to the dir changes.
  */
 const directionSubscribers = [];
-const directionUpdater = function () {
+function directionUpdater() {
   const documentDir = getDocumentDir();
   directionSubscribers.forEach((element) => {
     alignDirs(element, documentDir);
   });
-};
+}
 
 let scrollType;
 
 const directionObserver = new MutationObserver(directionUpdater);
 directionObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['dir'] });
 
-const alignDirs = function (element, documentDir, elementDir = element.getAttribute('dir')) {
+function alignDirs(element, documentDir, elementDir = element.getAttribute('dir')) {
   if (documentDir) {
     element.setAttribute('dir', documentDir);
   } else if (elementDir != null) {
     element.removeAttribute('dir');
   }
-};
+}
 
-const getDocumentDir = function () {
+function getDocumentDir() {
   return document.documentElement.getAttribute('dir');
-};
+}
 
 /**
  * A mixin to handle `dir` attribute based on the one set on the `<html>` element.

package/src/element-mixin.js

@@ -32,7 +32,7 @@ const registered = new Set();
 export const ElementMixin = (superClass) =>
   class VaadinElementMixin extends DirMixin(superClass) {
     static get version() {
-      return '22.0.0-rc1';
+      return '23.0.0-alpha2';
     }
 
     /** @protected */

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

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { ReactiveController } from 'lit';
+
+/**
+ * A controller for trapping focus within a DOM node.
+ */
+declare class FocusTrapController implements ReactiveController {
+  constructor(node: HTMLElement);
+
+  hostConnected(): void;
+
+  hostDisconnected(): void;
+
+  /**
+   * The controller host element.
+   */
+  host: HTMLElement;
+
+  /**
+   * 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,139 @@
+/**
+ * @license
+ * Copyright (c) 2021 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';
+
+/**
+ * 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);
+  }
+
+  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.');
+    }
+
+    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;
+  }
+
+  /**
+   * 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;
+    }
+
+    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;
+    focusableElements[nextIndex].focus();
+  }
+
+  /**
+   * 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() {
+    return this.__focusableElements.findIndex(isElementFocused);
+  }
+}

package/src/focus-utils.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * 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[];

package/src/focus-utils.js

@@ -0,0 +1,228 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * 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 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) || isElementHiddenDirectly(element)) {
+    return -1;
+  }
+
+  const tabIndex = element.getAttribute('tabindex') || 0;
+  return Number(tabIndex);
+}
+
+/**
+ * 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);
+}
+
+/**
+ * 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) {
+    // Don't traverse children if the node is not an HTML element.
+    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 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 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;
+}