@vaadin/component-base 23.2.15 → 23.2.16

package/src/iron-list-core.js

@@ -10,7 +10,7 @@
 import { animationFrame, idlePeriod, microTask } from './async.js';
 import { Debouncer, enqueueDebouncer, flush } from './debounce.js';
 
-const IOS = navigator.userAgent.match(/iP(?:hone|ad;(?: U;)? CPU) OS (\d+)/);
+const IOS = navigator.userAgent.match(/iP(?:hone|ad;(?: U;)? CPU) OS (\d+)/u);
 const IOS_TOUCH_SCROLLING = IOS && IOS[1] >= 8;
 const DEFAULT_PHYSICAL_COUNT = 3;
 
@@ -23,6 +23,7 @@ const DEFAULT_PHYSICAL_COUNT = 3;
  * If something in the scrolling engine needs to be changed
  * for the virtualizer's purposes, override a function
  * in virtualizer-iron-list-adapter.js instead of changing it here.
+ * If a function on this file is no longer needed, the code can be safely deleted.
  *
  * This will allow us to keep the iron-list code here as close to
  * the original as possible.
@@ -501,9 +502,12 @@ export const ironList = {
       this._physicalIndexForKey = {};
       this._firstVisibleIndexVal = null;
       this._lastVisibleIndexVal = null;
-      this._physicalCount = this._physicalCount || 0;
-      this._physicalItems = this._physicalItems || [];
-      this._physicalSizes = this._physicalSizes || [];
+      if (!this._physicalItems) {
+        this._physicalItems = [];
+      }
+      if (!this._physicalSizes) {
+        this._physicalSizes = [];
+      }
       this._physicalStart = 0;
       if (this._scrollTop > this._scrollOffset) {
         this._resetScrollPosition(0);
@@ -560,39 +564,6 @@ export const ironList = {
     return this._virtualStart + (this._physicalCount - this._physicalStart) + pidx;
   },
 
-  /**
-   * Updates the height for a given set of items.
-   *
-   * @param {!Array<number>=} itemSet
-   */
-  _updateMetrics(itemSet) {
-    // Make sure we distributed all the physical items
-    // so we can measure them.
-    flush();
-
-    let newPhysicalSize = 0;
-    let oldPhysicalSize = 0;
-    const prevAvgCount = this._physicalAverageCount;
-    const prevPhysicalAvg = this._physicalAverage;
-
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    this._iterateItems((pidx, vidx) => {
-      oldPhysicalSize += this._physicalSizes[pidx];
-      this._physicalSizes[pidx] = this._physicalItems[pidx].offsetHeight;
-      newPhysicalSize += this._physicalSizes[pidx];
-      this._physicalAverageCount += this._physicalSizes[pidx] ? 1 : 0;
-    }, itemSet);
-
-    this._physicalSize = this._physicalSize + newPhysicalSize - oldPhysicalSize;
-
-    // Update the average if it measured something.
-    if (this._physicalAverageCount !== prevAvgCount) {
-      this._physicalAverage = Math.round(
-        (prevPhysicalAvg * prevAvgCount + newPhysicalSize) / this._physicalAverageCount,
-      );
-    }
-  },
-
   /**
    * Updates the position of the physical items.
    */
@@ -645,16 +616,21 @@ export const ironList = {
    * @param {boolean=} forceUpdate If true, updates the height no matter what.
    */
   _updateScrollerSize(forceUpdate) {
-    this._estScrollHeight =
+    const estScrollHeight =
       this._physicalBottom +
       Math.max(this._virtualCount - this._physicalCount - this._virtualStart, 0) * this._physicalAverage;
 
-    forceUpdate = forceUpdate || this._scrollHeight === 0;
-    forceUpdate = forceUpdate || this._scrollPosition >= this._estScrollHeight - this._physicalSize;
+    this._estScrollHeight = estScrollHeight;
+
     // Amortize height adjustment, so it won't trigger large repaints too often.
-    if (forceUpdate || Math.abs(this._estScrollHeight - this._scrollHeight) >= this._viewportHeight) {
-      this.$.items.style.height = `${this._estScrollHeight}px`;
-      this._scrollHeight = this._estScrollHeight;
+    if (
+      forceUpdate ||
+      this._scrollHeight === 0 ||
+      this._scrollPosition >= estScrollHeight - this._physicalSize ||
+      Math.abs(estScrollHeight - this._scrollHeight) >= this._viewportHeight
+    ) {
+      this.$.items.style.height = `${estScrollHeight}px`;
+      this._scrollHeight = estScrollHeight;
     }
   },
 
@@ -750,7 +726,9 @@ export const ironList = {
   },
 
   _debounce(name, cb, asyncModule) {
-    this._debouncers = this._debouncers || {};
+    if (!this._debouncers) {
+      this._debouncers = {};
+    }
     this._debouncers[name] = Debouncer.debounce(this._debouncers[name], asyncModule, cb.bind(this));
     enqueueDebouncer(this._debouncers[name]);
   },

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

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

package/src/keyboard-mixin.js

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

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;
+}