@vaadin/component-base 23.3.3 → 24.0.0-alpha10

package/src/list-mixin.js

@@ -0,0 +1,343 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2023 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 { getNormalizedScrollLeft, setNormalizedScrollLeft } from './dir-utils.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)'];
+    }
+
+    /**
+     * @return {boolean}
+     * @protected
+     */
+    get _isRTL() {
+      return !this._vertical && this.getAttribute('dir') === 'rtl';
+    }
+
+    /**
+     * @return {!HTMLElement}
+     * @protected
+     */
+    get _scrollerElement() {
+      // Returning scroller element of the component
+      console.warn(`Please implement the '_scrollerElement' property in <${this.localName}>`);
+      return this;
+    }
+
+    /**
+     * @return {boolean}
+     * @protected
+     */
+    get _vertical() {
+      return this.orientation !== 'horizontal';
+    }
+
+    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);
+    }
+
+    /** @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);
+    }
+
+    /**
+     * 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]/u.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);
+    }
+
+    /**
+     * 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);
+    }
+
+    /**
+     * @param {number} pixels
+     * @protected
+     */
+    _scroll(pixels) {
+      if (this._vertical) {
+        this._scrollerElement.scrollTop += pixels;
+      } else {
+        const dir = this.getAttribute('dir') || 'ltr';
+        const scrollLeft = getNormalizedScrollLeft(this._scrollerElement, dir) + pixels;
+        setNormalizedScrollLeft(this._scrollerElement, dir, 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/media-query-controller.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 { ReactiveController } from 'lit';

package/src/media-query-controller.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/
  */
 

package/src/overflow-controller.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 { ReactiveController } from 'lit';

package/src/overflow-controller.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 { FlattenedNodesObserver } from '@polymer/polymer/lib/utils/flattened-nodes-observer.js';

package/src/overlay-class-mixin.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright (c) 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';
+
+/**
+ * A mixin that forwards CSS class names to the internal overlay element
+ * by setting the `overlayClass` property or `overlay-class` attribute.
+ */
+export declare function OverlayClassMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<OverlayClassMixinClass> & T;
+
+export declare class OverlayClassMixinClass {
+  /**
+   * A space-delimited list of CSS class names to set on the overlay element.
+   * This property does not affect other CSS class names set manually via JS.
+   *
+   * Note, if the CSS class name was set with this property, clearing it will
+   * remove it from the overlay, even if the same class name was also added
+   * manually, e.g. by using `classList.add()` in the `renderer` function.
+   *
+   * @attr {string} overlay-class
+   */
+  overlayClass: string;
+
+  /**
+   * An overlay element on which CSS class names are set.
+   */
+  protected _overlayElement: HTMLElement;
+}

package/src/overlay-class-mixin.js

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright (c) 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * A mixin that forwards CSS class names to the internal overlay element
+ * by setting the `overlayClass` property or `overlay-class` attribute.
+ *
+ * @polymerMixin
+ */
+export const OverlayClassMixin = (superclass) =>
+  class OverlayClassMixinClass extends superclass {
+    static get properties() {
+      return {
+        /**
+         * A space-delimited list of CSS class names to set on the overlay element.
+         * This property does not affect other CSS class names set manually via JS.
+         *
+         * Note, if the CSS class name was set with this property, clearing it will
+         * remove it from the overlay, even if the same class name was also added
+         * manually, e.g. by using `classList.add()` in the `renderer` function.
+         *
+         * @attr {string} overlay-class
+         */
+        overlayClass: {
+          type: String,
+        },
+
+        /**
+         * An overlay element on which CSS class names are set.
+         *
+         * @protected
+         */
+        _overlayElement: {
+          type: Object,
+        },
+      };
+    }
+
+    static get observers() {
+      return ['__updateOverlayClassNames(overlayClass, _overlayElement)'];
+    }
+
+    /** @private */
+    __updateOverlayClassNames(overlayClass, overlayElement) {
+      if (!overlayElement) {
+        return;
+      }
+
+      // Overlay is set but overlayClass is not set
+      if (overlayClass === undefined) {
+        return;
+      }
+
+      const { classList } = overlayElement;
+
+      if (!this.__initialClasses) {
+        this.__initialClasses = new Set(classList);
+      }
+
+      if (Array.isArray(this.__previousClasses)) {
+        // Remove old classes that no longer apply
+        const classesToRemove = this.__previousClasses.filter((name) => !this.__initialClasses.has(name));
+        if (classesToRemove.length > 0) {
+          classList.remove(...classesToRemove);
+        }
+      }
+
+      // Add new classes based on the overlayClass
+      const classesToAdd = typeof overlayClass === 'string' ? overlayClass.split(' ') : [];
+      if (classesToAdd.length > 0) {
+        classList.add(...classesToAdd);
+      }
+
+      this.__previousClasses = classesToAdd;
+    }
+  };

package/src/polylit-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/polylit-mixin.js

@@ -1,16 +1,18 @@
 /**
  * @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 { dedupeMixin } from '@open-wc/dedupe-mixin';
 
 const caseMap = {};
 
-const CAMEL_TO_DASH = /([A-Z])/g;
+const CAMEL_TO_DASH = /([A-Z])/gu;
 
 function camelToDash(camel) {
-  caseMap[camel] = caseMap[camel] || camel.replace(CAMEL_TO_DASH, '-$1').toLowerCase();
+  if (!caseMap[camel]) {
+    caseMap[camel] = camel.replace(CAMEL_TO_DASH, '-$1').toLowerCase();
+  }
   return caseMap[camel];
 }
 
@@ -169,7 +171,10 @@ const PolylitMixinImplementation = (superclass) => {
     firstUpdated() {
       super.firstUpdated();
 
-      this.$ = this.$ || {};
+      if (!this.$) {
+        this.$ = {};
+      }
+
       this.shadowRoot.querySelectorAll('[id]').forEach((node) => {
         this.$[node.id] = node;
       });

package/src/resize-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/resize-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';
@@ -28,6 +28,16 @@ const observer = new ResizeObserver((entries) => {
 export const ResizeMixin = dedupingMixin(
   (superclass) =>
     class ResizeMixinClass extends superclass {
+      /**
+       * When true, the parent element resize will be also observed.
+       * Override this getter and return `true` to enable this.
+       *
+       * @protected
+       */
+      get _observeParent() {
+        return false;
+      }
+
       /** @protected */
       connectedCallback() {
         super.connectedCallback();
@@ -67,16 +77,6 @@ export const ResizeMixin = dedupingMixin(
         }
       }
 
-      /**
-       * When true, the parent element resize will be also observed.
-       * Override this getter and return `true` to enable this.
-       *
-       * @protected
-       */
-      get _observeParent() {
-        return false;
-      }
-
       /**
        * A handler invoked on host resize. By default, it does nothing.
        * Override the method to implement your own behavior.
@@ -86,15 +86,5 @@ export const ResizeMixin = dedupingMixin(
       _onResize(_contentRect) {
         // To be implemented.
       }
-
-      /**
-       * @deprecated Since Vaadin 23, `notifyResize()` is deprecated. The component uses a
-       * ResizeObserver internally and doesn't need to be explicitly notified of resizes.
-       */
-      notifyResize() {
-        console.warn(
-          `WARNING: Since Vaadin 23, notifyResize() is deprecated. The component uses a ResizeObserver internally and doesn't need to be explicitly notified of resizes.`,
-        );
-      }
     },
 );

package/src/slot-child-observe-controller.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright (c) 2022 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { SlotController } from './slot-controller.js';
+
+/**
+ * A controller that observes slotted element mutations, especially ID attribute
+ * and the text content, and fires an event to notify host element about those.
+ */
+export class SlotChildObserveController extends SlotController {
+  /**
+   * Setup the mutation observer on the node to update ID and notify host.
+   * Node doesn't get observed automatically until this method is called.
+   */
+  protected observeNode(node: Node): void;
+
+  /**
+   * Override to restore default node when a custom one is removed.
+   */
+  protected restoreDefaultNode(): void;
+
+  /**
+   * Override to update default node text on property change.
+   */
+  protected updateDefaultNode(node: Node): void;
+}