@vaadin/component-base 23.0.0-alpha1 → 23.0.0-alpha5

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": "23.0.0-alpha1",
+  "version": "23.0.0-alpha5",
   "publishConfig": {
     "access": "public"
   },
@@ -18,6 +18,7 @@
   },
   "main": "index.js",
   "module": "index.js",
+  "type": "module",
   "files": [
     "custom_typings",
     "index.d.ts",
@@ -41,5 +42,5 @@
     "@vaadin/testing-helpers": "^0.3.2",
     "sinon": "^9.2.4"
   },
-  "gitHead": "fbcb07328fdf88260e3b461088d207426b21c710"
+  "gitHead": "74f9294964eb8552d96578c14af6ad214f5257bc"
 }

package/src/a11y-announcer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright (c) 2022 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * Cause a text string to be announced by screen readers.
+ */
+export function announce(text: string, options?: { mode?: 'polite' | 'assertive'; timeout?: number }): void;

package/src/a11y-announcer.js

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright (c) 2022 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+const region = document.createElement('div');
+
+region.style.position = 'fixed';
+region.style.clip = 'rect(0px, 0px, 0px, 0px)';
+region.setAttribute('aria-live', 'polite');
+
+document.body.appendChild(region);
+
+/**
+ * Cause a text string to be announced by screen readers.
+ *
+ * @param {string} text The text that should be announced by the screen reader.
+ * @param {{mode?: string, timeout?: number}} options Additional options.
+ */
+export function announce(text, options = {}) {
+  const mode = options.mode || 'polite';
+  const timeout = options.timeout === undefined ? 150 : options.timeout;
+
+  region.setAttribute('aria-live', mode);
+
+  region.textContent = '';
+
+  setTimeout(() => {
+    region.textContent = text;
+  }, timeout);
+}

package/src/active-mixin.d.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { Constructor } from '@open-wc/dedupe-mixin';

package/src/active-mixin.js

@@ -1,9 +1,9 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 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();
@@ -182,10 +182,13 @@ const microTask = {
   run(callback) {
     if (!microtaskScheduled) {
       microtaskScheduled = true;
-      microtaskNode.textContent = microtaskNodeContent++;
+      microtaskNode.textContent = microtaskNodeContent;
+      microtaskNodeContent += 1;
     }
     microtaskCallbacks.push(callback);
-    return microtaskCurrHandle++;
+    const result = microtaskCurrHandle;
+    microtaskCurrHandle += 1;
+    return result;
   },
 
   /**

package/src/browser-utils.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 

package/src/controller-mixin.d.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { Constructor } from '@open-wc/dedupe-mixin';

package/src/controller-mixin.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 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';

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.d.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 

package/src/dir-helper.js

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

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { Constructor } from '@open-wc/dedupe-mixin';

package/src/dir-mixin.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { DirHelper } from './dir-helper.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/disabled-mixin.d.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { Constructor } from '@open-wc/dedupe-mixin';

package/src/disabled-mixin.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 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';

package/src/element-mixin.d.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import '../custom_typings/vaadin-usage-statistics.js';

package/src/element-mixin.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { usageStatistics } from '@vaadin/vaadin-usage-statistics/vaadin-usage-statistics.js';
@@ -32,7 +32,7 @@ const registered = new Set();
 export const ElementMixin = (superClass) =>
   class VaadinElementMixin extends DirMixin(superClass) {
     static get version() {
-      return '23.0.0-alpha1';
+      return '23.0.0-alpha5';
     }
 
     /** @protected */

package/src/focus-mixin.d.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { Constructor } from '@open-wc/dedupe-mixin';

package/src/focus-mixin.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2021 - 2022 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';

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

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2022 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.
+ */
+export 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 - 2022 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 - 2022 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[];