@vaadin/component-base 24.0.0-rc2 → 24.1.0-alpha1

package/src/focus-mixin.js

@@ -1,93 +0,0 @@
-/**
- * @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

@@ -1,39 +0,0 @@
-/**
- * @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

@@ -1,155 +0,0 @@
-/**
- * @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

@@ -1,51 +0,0 @@
-/**
- * @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[];

package/src/focus-utils.js

@@ -1,260 +0,0 @@
-/**
- * @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

@@ -1,41 +0,0 @@
-/**
- * @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;
-}