@vaadin/component-base 24.0.0-alpha3 → 24.0.0-alpha5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/component-base",
-  "version": "24.0.0-alpha3",
+  "version": "24.0.0-alpha5",
   "publishConfig": {
     "access": "public"
   },
@@ -42,5 +42,5 @@
     "@vaadin/testing-helpers": "^0.3.2",
     "sinon": "^13.0.2"
   },
-  "gitHead": "7a013a3c5a56abd61dd4f7773c6ec77c3541bdf2"
+  "gitHead": "fc0b1721eda9e39cb289b239e440fc9e29573a31"
 }

package/src/dir-mixin.d.ts

@@ -11,6 +11,8 @@ import type { Constructor } from '@open-wc/dedupe-mixin';
 export declare function DirMixin<T extends Constructor<HTMLElement>>(base: T): Constructor<DirMixinClass> & T;
 
 export declare class DirMixinClass {
+  protected readonly __isRTL: boolean;
+
   protected __getNormalizedScrollLeft(element: Element | null): number;
 
   protected __setNormalizedScrollLeft(element: Element | null, scrollLeft: number): void;

package/src/dir-mixin.js

@@ -112,6 +112,14 @@ export const DirMixin = (superClass) =>
       this.__unsubscribe();
     }
 
+    /**
+     * @return {boolean}
+     * @protected
+     */
+    get __isRTL() {
+      return this.getAttribute('dir') === 'rtl';
+    }
+
     /** @protected */
     _valueToNodeAttribute(node, value, attribute) {
       // Override default Polymer attribute reflection to match native behavior of HTMLElement.dir property

package/src/element-mixin.js

@@ -39,7 +39,7 @@ const registered = new Set();
 export const ElementMixin = (superClass) =>
   class VaadinElementMixin extends DirMixin(superClass) {
     static get version() {
-      return '24.0.0-alpha3';
+      return '24.0.0-alpha5';
     }
 
     /** @protected */

package/src/list-mixin.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2022 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;
+
+  /**
+   * 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;
+}

package/src/list-mixin.js

@@ -0,0 +1,344 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2022 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { FlattenedNodesObserver } from '@polymer/polymer/lib/utils/flattened-nodes-observer.js';
+import { timeOut } from './async.js';
+import { Debouncer } from './debounce.js';
+import { DirHelper } from './dir-helper.js';
+import { KeyboardDirectionMixin } from './keyboard-direction-mixin.js';
+
+/**
+ * A mixin for list elements, facilitating navigation and selection of items.
+ *
+ * @polymerMixin
+ * @mixes KeyboardDirectionMixin
+ */
+export const ListMixin = (superClass) =>
+  class ListMixinClass extends KeyboardDirectionMixin(superClass) {
+    static get properties() {
+      return {
+        /**
+         * Used for mixin detection because `instanceof` does not work with mixins.
+         * @type {boolean}
+         */
+        _hasVaadinListMixin: {
+          value: true,
+        },
+
+        /**
+         * The index of the item selected in the items array.
+         * Note: Not updated when used in `multiple` selection mode.
+         */
+        selected: {
+          type: Number,
+          reflectToAttribute: true,
+          notify: true,
+        },
+
+        /**
+         * Define how items are disposed in the dom.
+         * Possible values are: `horizontal|vertical`.
+         * It also changes navigation keys from left/right to up/down.
+         * @type {!ListOrientation}
+         */
+        orientation: {
+          type: String,
+          reflectToAttribute: true,
+          value: '',
+        },
+
+        /**
+         * 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.
+         * @type {!Array<!Element> | undefined}
+         */
+        items: {
+          type: Array,
+          readOnly: true,
+          notify: true,
+        },
+
+        /**
+         * The search buffer for the keyboard selection feature.
+         * @private
+         */
+        _searchBuf: {
+          type: String,
+          value: '',
+        },
+      };
+    }
+
+    static get observers() {
+      return ['_enhanceItems(items, orientation, selected, disabled)'];
+    }
+
+    /** @protected */
+    ready() {
+      super.ready();
+
+      this.addEventListener('click', (e) => this._onClick(e));
+
+      this._observer = new FlattenedNodesObserver(this, () => {
+        this._setItems(this._filterItems(FlattenedNodesObserver.getFlattenedNodes(this)));
+      });
+    }
+
+    /**
+     * Override method inherited from `KeyboardDirectionMixin`
+     * to use the stored list of item elements.
+     *
+     * @return {Element[]}
+     * @protected
+     * @override
+     */
+    _getItems() {
+      return this.items;
+    }
+
+    /** @private */
+    _enhanceItems(items, orientation, selected, disabled) {
+      if (!disabled) {
+        if (items) {
+          this.setAttribute('aria-orientation', orientation || 'vertical');
+          this.items.forEach((item) => {
+            if (orientation) {
+              item.setAttribute('orientation', orientation);
+            } else {
+              item.removeAttribute('orientation');
+            }
+          });
+
+          this._setFocusable(selected || 0);
+
+          const itemToSelect = items[selected];
+          items.forEach((item) => {
+            item.selected = item === itemToSelect;
+          });
+          if (itemToSelect && !itemToSelect.disabled) {
+            this._scrollToItem(selected);
+          }
+        }
+      }
+    }
+
+    /**
+     * @param {!Array<!Element>} array
+     * @return {!Array<!Element>}
+     * @protected
+     */
+    _filterItems(array) {
+      return array.filter((e) => e._hasVaadinItemMixin);
+    }
+
+    /**
+     * @param {!MouseEvent} event
+     * @protected
+     */
+    _onClick(event) {
+      if (event.metaKey || event.shiftKey || event.ctrlKey || event.defaultPrevented) {
+        return;
+      }
+
+      const item = this._filterItems(event.composedPath())[0];
+      let idx;
+      if (item && !item.disabled && (idx = this.items.indexOf(item)) >= 0) {
+        this.selected = idx;
+      }
+    }
+
+    /**
+     * @param {number} currentIdx
+     * @param {string} key
+     * @return {number}
+     * @protected
+     */
+    _searchKey(currentIdx, key) {
+      this._searchReset = Debouncer.debounce(this._searchReset, timeOut.after(500), () => {
+        this._searchBuf = '';
+      });
+      this._searchBuf += key.toLowerCase();
+
+      if (!this.items.some((item) => this.__isMatchingKey(item))) {
+        this._searchBuf = key.toLowerCase();
+      }
+
+      const idx = this._searchBuf.length === 1 ? currentIdx + 1 : currentIdx;
+      return this._getAvailableIndex(
+        this.items,
+        idx,
+        1,
+        (item) => this.__isMatchingKey(item) && getComputedStyle(item).display !== 'none',
+      );
+    }
+
+    /** @private */
+    __isMatchingKey(item) {
+      return item.textContent
+        .replace(/[^\p{L}\p{Nd}]/gu, '')
+        .toLowerCase()
+        .startsWith(this._searchBuf);
+    }
+
+    /**
+     * @return {boolean}
+     * @protected
+     */
+    get _isRTL() {
+      return !this._vertical && this.getAttribute('dir') === 'rtl';
+    }
+
+    /**
+     * Override an event listener from `KeyboardMixin`
+     * to search items by key.
+     *
+     * @param {!KeyboardEvent} event
+     * @protected
+     * @override
+     */
+    _onKeyDown(event) {
+      if (event.metaKey || event.ctrlKey) {
+        return;
+      }
+
+      const key = event.key;
+
+      const currentIdx = this.items.indexOf(this.focused);
+      if (/[a-zA-Z0-9]/.test(key) && key.length === 1) {
+        const idx = this._searchKey(currentIdx, key);
+        if (idx >= 0) {
+          this._focus(idx);
+        }
+        return;
+      }
+
+      super._onKeyDown(event);
+    }
+
+    /**
+     * @param {!Element} item
+     * @return {boolean}
+     * @protected
+     */
+    _isItemHidden(item) {
+      return getComputedStyle(item).display === 'none';
+    }
+
+    /**
+     * @param {number} idx
+     * @protected
+     */
+    _setFocusable(idx) {
+      idx = this._getAvailableIndex(this.items, idx, 1);
+      const item = this.items[idx];
+      this.items.forEach((e) => {
+        e.tabIndex = e === item ? 0 : -1;
+      });
+    }
+
+    /**
+     * @param {number} idx
+     * @protected
+     */
+    _focus(idx) {
+      this.items.forEach((e, index) => {
+        e.focused = index === idx;
+      });
+      this._setFocusable(idx);
+      this._scrollToItem(idx);
+      super._focus(idx);
+    }
+
+    focus() {
+      // In initialization (e.g vaadin-select) observer might not been run yet.
+      if (this._observer) {
+        this._observer.flush();
+      }
+      const firstItem = this.querySelector('[tabindex="0"]') || (this.items ? this.items[0] : null);
+      this._focusItem(firstItem);
+    }
+
+    /**
+     * @return {!HTMLElement}
+     * @protected
+     */
+    get _scrollerElement() {
+      // Returning scroller element of the component
+      console.warn(`Please implement the '_scrollerElement' property in <${this.localName}>`);
+      return this;
+    }
+
+    /**
+     * Scroll the container to have the next item by the edge of the viewport.
+     * @param {number} idx
+     * @protected
+     */
+    _scrollToItem(idx) {
+      const item = this.items[idx];
+      if (!item) {
+        return;
+      }
+
+      const props = this._vertical ? ['top', 'bottom'] : this._isRTL ? ['right', 'left'] : ['left', 'right'];
+
+      const scrollerRect = this._scrollerElement.getBoundingClientRect();
+      const nextItemRect = (this.items[idx + 1] || item).getBoundingClientRect();
+      const prevItemRect = (this.items[idx - 1] || item).getBoundingClientRect();
+
+      let scrollDistance = 0;
+      if (
+        (!this._isRTL && nextItemRect[props[1]] >= scrollerRect[props[1]]) ||
+        (this._isRTL && nextItemRect[props[1]] <= scrollerRect[props[1]])
+      ) {
+        scrollDistance = nextItemRect[props[1]] - scrollerRect[props[1]];
+      } else if (
+        (!this._isRTL && prevItemRect[props[0]] <= scrollerRect[props[0]]) ||
+        (this._isRTL && prevItemRect[props[0]] >= scrollerRect[props[0]])
+      ) {
+        scrollDistance = prevItemRect[props[0]] - scrollerRect[props[0]];
+      }
+
+      this._scroll(scrollDistance);
+    }
+
+    /**
+     * @return {boolean}
+     * @protected
+     */
+    get _vertical() {
+      return this.orientation !== 'horizontal';
+    }
+
+    /**
+     * @param {number} pixels
+     * @protected
+     */
+    _scroll(pixels) {
+      if (this._vertical) {
+        this._scrollerElement.scrollTop += pixels;
+      } else {
+        const dir = this.getAttribute('dir') || 'ltr';
+        const scrollType = DirHelper.detectScrollType();
+        const scrollLeft = DirHelper.getNormalizedScrollLeft(scrollType, dir, this._scrollerElement) + pixels;
+        DirHelper.setNormalizedScrollLeft(scrollType, dir, this._scrollerElement, scrollLeft);
+      }
+    }
+
+    /**
+     * Fired when the selection is changed.
+     * Not fired when used in `multiple` selection mode.
+     *
+     * @event selected-changed
+     * @param {Object} detail
+     * @param {Object} detail.value the index of the item selected in the items array.
+     */
+  };

package/src/slot-controller.d.ts

@@ -16,8 +16,16 @@ export class SlotController extends EventTarget implements ReactiveController {
    */
   node: HTMLElement;
 
+  /**
+   * The list of slotted nodes managed by the controller.
+   * Only used when `multiple` property is set to `true`.
+   */
+  nodes: HTMLElement[];
+
   protected initialized: boolean;
 
+  protected multiple: boolean;
+
   protected defaultNode: Node;
 
   protected defaultId: string;
@@ -27,6 +35,7 @@ export class SlotController extends EventTarget implements ReactiveController {
     slotName: string,
     tagName?: string,
     config?: {
+      multiple?: boolean;
       observe?: boolean;
       useUniqueId?: boolean;
       initializer?(host: HTMLElement, node: HTMLElement): void;
@@ -35,6 +44,11 @@ export class SlotController extends EventTarget implements ReactiveController {
 
   hostConnected(): void;
 
+  /**
+   * Return the list of nodes matching the slot managed by the controller.
+   */
+  getSlotChildren(): Node[];
+
   /**
    * Return a reference to the node managed by the controller.
    */
@@ -42,6 +56,8 @@ export class SlotController extends EventTarget implements ReactiveController {
 
   protected attachDefaultNode(): Node | undefined;
 
+  protected initAddedNode(node: Node): void;
+
   protected initNode(node: Node): void;
 
   /**

package/src/slot-controller.js

@@ -4,6 +4,7 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { FlattenedNodesObserver } from '@polymer/polymer/lib/utils/flattened-nodes-observer.js';
+import { isEmptyTextNode } from './dom-utils.js';
 import { generateUniqueId } from './unique-id-utils.js';
 
 /**
@@ -26,14 +27,19 @@ export class SlotController extends EventTarget {
   constructor(host, slotName, tagName, config = {}) {
     super();
 
-    const { initializer, observe, useUniqueId } = config;
+    const { initializer, multiple, observe, useUniqueId } = config;
 
     this.host = host;
     this.slotName = slotName;
     this.tagName = tagName;
     this.observe = typeof observe === 'boolean' ? observe : true;
+    this.multiple = typeof multiple === 'boolean' ? multiple : false;
     this.slotInitializer = initializer;
 
+    if (multiple) {
+      this.nodes = [];
+    }
+
     // Only generate the default ID if requested by the controller.
     if (useUniqueId) {
       this.defaultId = SlotController.generateId(slotName, host);
@@ -42,17 +48,12 @@ export class SlotController extends EventTarget {
 
   hostConnected() {
     if (!this.initialized) {
-      let node = this.getSlotChild();
-
-      if (!node) {
-        node = this.attachDefaultNode();
+      if (this.multiple) {
+        this.initMultiple();
       } else {
-        this.node = node;
-        this.initCustomNode(node);
+        this.initSingle();
       }
 
-      this.initNode(node);
-
       if (this.observe) {
         this.observeSlot();
       }
@@ -61,6 +62,35 @@ export class SlotController extends EventTarget {
     }
   }
 
+  /** @protected */
+  initSingle() {
+    let node = this.getSlotChild();
+
+    if (!node) {
+      node = this.attachDefaultNode();
+      this.initNode(node);
+    } else {
+      this.node = node;
+      this.initAddedNode(node);
+    }
+  }
+
+  /** @protected */
+  initMultiple() {
+    const children = this.getSlotChildren();
+
+    if (children.length === 0) {
+      const defaultNode = this.attachDefaultNode();
+      this.nodes = [defaultNode];
+      this.initNode(defaultNode);
+    } else {
+      this.nodes = children;
+      children.forEach((node) => {
+        this.initAddedNode(node);
+      });
+    }
+  }
+
   /**
    * Create and attach default node using the slot factory.
    * @return {Node | undefined}
@@ -92,12 +122,12 @@ export class SlotController extends EventTarget {
   }
 
   /**
-   * Return a reference to the node managed by the controller.
+   * Return the list of nodes matching the slot managed by the controller.
    * @return {Node}
    */
-  getSlotChild() {
+  getSlotChildren() {
     const { slotName } = this;
-    return Array.from(this.host.childNodes).find((node) => {
+    return Array.from(this.host.childNodes).filter((node) => {
       // Either an element (any slot) or a text node (only un-named slot).
       return (
         (node.nodeType === Node.ELEMENT_NODE && node.slot === slotName) ||
@@ -106,6 +136,14 @@ export class SlotController extends EventTarget {
     });
   }
 
+  /**
+   * Return a reference to the node managed by the controller.
+   * @return {Node}
+   */
+  getSlotChild() {
+    return this.getSlotChildren()[0];
+  }
+
   /**
    * @param {Node} node
    * @protected
@@ -135,6 +173,14 @@ export class SlotController extends EventTarget {
    */
   teardownNode(_node) {}
 
+  /** @protected */
+  initAddedNode(node) {
+    if (node !== this.defaultNode) {
+      this.initCustomNode(node);
+      this.initNode(node);
+    }
+  }
+
   /**
    * Setup the observer to manage slot content changes.
    * @protected
@@ -145,9 +191,11 @@ export class SlotController extends EventTarget {
     const slot = this.host.shadowRoot.querySelector(selector);
 
     this.__slotObserver = new FlattenedNodesObserver(slot, (info) => {
-      // TODO: support default slot with multiple nodes (e.g. confirm-dialog)
-      const current = this.node;
-      const newNode = info.addedNodes.find((node) => node !== current);
+      const current = this.multiple ? this.nodes : [this.node];
+
+      // Calling `slot.assignedNodes()` includes whitespace text nodes in case of default slot:
+      // unlike comment nodes, they are not filtered out. So we need to manually ignore them.
+      const newNodes = info.addedNodes.filter((node) => !isEmptyTextNode(node) && !current.includes(node));
 
       if (info.removedNodes.length) {
         info.removedNodes.forEach((node) => {
@@ -155,18 +203,22 @@ export class SlotController extends EventTarget {
         });
       }
 
-      if (newNode) {
+      if (newNodes && newNodes.length > 0) {
         // Custom node is added, remove the current one.
-        if (current && current.isConnected) {
-          this.host.removeChild(current);
-        }
-
-        this.node = newNode;
-
-        if (newNode !== this.defaultNode) {
-          this.initCustomNode(newNode);
+        current.forEach((node) => {
+          if (node && node.isConnected) {
+            node.parentNode.removeChild(node);
+          }
+        });
 
-          this.initNode(newNode);
+        if (this.multiple) {
+          this.nodes = newNodes;
+          newNodes.forEach((node) => {
+            this.initAddedNode(node);
+          });
+        } else {
+          this.node = newNodes[0];
+          this.initAddedNode(this.node);
         }
       }
     });