@vaadin/component-base 24.2.0-dev.f254716fe → 24.3.0-alpha2

package/src/slot-observer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright (c) 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * A helper for observing slot changes.
+ */
+export class SlotObserver {
+  constructor(
+    slot: HTMLSlotElement,
+    callback: (info: { addedNodes: Node[]; movedNodes: Node[]; removedNodes: Node[] }) => void,
+  );
+
+  /**
+   * Activates an observer. This method is automatically called when
+   * a `SlotObserver` is created. It should only be called to  re-activate
+   * an observer that has been deactivated via the `disconnect` method.
+   */
+  connect(): void;
+
+  /**
+   * Deactivates the observer. After calling this method the observer callback
+   * will not be called when changes to slotted nodes occur. The `connect` method
+   * may be subsequently called to reactivate the observer.
+   */
+  disconnect(): void;
+
+  /**
+   * Run the observer callback synchronously.
+   */
+  flush(): void;
+}

package/src/slot-observer.js

@@ -0,0 +1,105 @@
+/**
+ * @license
+ * Copyright (c) 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * A helper for observing slot changes.
+ */
+export class SlotObserver {
+  constructor(slot, callback) {
+    /** @type HTMLSlotElement */
+    this.slot = slot;
+
+    /** @type Function */
+    this.callback = callback;
+
+    /** @type {Node[]} */
+    this._storedNodes = [];
+
+    this._connected = false;
+    this._scheduled = false;
+
+    this._boundSchedule = () => {
+      this._schedule();
+    };
+
+    this.connect();
+    this._schedule();
+  }
+
+  /**
+   * Activates an observer. This method is automatically called when
+   * a `SlotObserver` is created. It should only be called to  re-activate
+   * an observer that has been deactivated via the `disconnect` method.
+   */
+  connect() {
+    this.slot.addEventListener('slotchange', this._boundSchedule);
+    this._connected = true;
+  }
+
+  /**
+   * Deactivates the observer. After calling this method the observer callback
+   * will not be called when changes to slotted nodes occur. The `connect` method
+   * may be subsequently called to reactivate the observer.
+   */
+  disconnect() {
+    this.slot.removeEventListener('slotchange', this._boundSchedule);
+    this._connected = false;
+  }
+
+  /** @private */
+  _schedule() {
+    if (!this._scheduled) {
+      this._scheduled = true;
+
+      queueMicrotask(() => {
+        this.flush();
+      });
+    }
+  }
+
+  /**
+   * Run the observer callback synchronously.
+   */
+  flush() {
+    if (!this._connected) {
+      return;
+    }
+
+    this._scheduled = false;
+
+    this._processNodes();
+  }
+
+  /** @private */
+  _processNodes() {
+    const currentNodes = this.slot.assignedNodes({ flatten: true });
+
+    let addedNodes = [];
+    const removedNodes = [];
+    const movedNodes = [];
+
+    if (currentNodes.length) {
+      addedNodes = currentNodes.filter((node) => !this._storedNodes.includes(node));
+    }
+
+    if (this._storedNodes.length) {
+      this._storedNodes.forEach((node, index) => {
+        const idx = currentNodes.indexOf(node);
+        if (idx === -1) {
+          removedNodes.push(node);
+        } else if (idx !== index) {
+          movedNodes.push(node);
+        }
+      });
+    }
+
+    if (addedNodes.length || removedNodes.length || movedNodes.length) {
+      this.callback({ addedNodes, movedNodes, removedNodes });
+    }
+
+    this._storedNodes = currentNodes;
+  }
+}

package/src/slot-styles-mixin.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @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 { Constructor } from '@open-wc/dedupe-mixin';
+
+/**
+ * Mixin to insert styles into the outer scope to handle slotted components.
+ * This is useful e.g. to hide native `<input type="number">` controls.
+ */
+export declare function SlotStylesMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<SlotStylesMixinClass> & T;
+
+export declare class SlotStylesMixinClass {
+  /**
+   * List of styles to insert into root.
+   */
+  protected readonly slotStyles: string[];
+}

package/src/slot-styles-mixin.js

@@ -0,0 +1,76 @@
+/**
+ * @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';
+
+const stylesMap = new WeakMap();
+
+/**
+ * Get all the styles inserted into root.
+ * @param {DocumentOrShadowRoot} root
+ * @return {Set<string>}
+ */
+function getRootStyles(root) {
+  if (!stylesMap.has(root)) {
+    stylesMap.set(root, new Set());
+  }
+
+  return stylesMap.get(root);
+}
+
+/**
+ * Insert styles into the root.
+ * @param {string} styles
+ * @param {DocumentOrShadowRoot} root
+ */
+function insertStyles(styles, root) {
+  const style = document.createElement('style');
+  style.textContent = styles;
+
+  if (root === document) {
+    document.head.appendChild(style);
+  } else {
+    root.insertBefore(style, root.firstChild);
+  }
+}
+
+/**
+ * Mixin to insert styles into the outer scope to handle slotted components.
+ * This is useful e.g. to hide native `<input type="number">` controls.
+ *
+ * @polymerMixin
+ */
+export const SlotStylesMixin = dedupingMixin(
+  (superclass) =>
+    class SlotStylesMixinClass extends superclass {
+      /**
+       * List of styles to insert into root.
+       * @protected
+       */
+      get slotStyles() {
+        return {};
+      }
+
+      /** @protected */
+      connectedCallback() {
+        super.connectedCallback();
+
+        this.__applySlotStyles();
+      }
+
+      /** @private */
+      __applySlotStyles() {
+        const root = this.getRootNode();
+        const rootStyles = getRootStyles(root);
+
+        this.slotStyles.forEach((styles) => {
+          if (!rootStyles.has(styles)) {
+            insertStyles(styles, root);
+            rootStyles.add(styles);
+          }
+        });
+      }
+    },
+);

package/src/tooltip-controller.d.ts

@@ -23,6 +23,13 @@ type TooltipPosition =
  * A controller that manages the slotted tooltip element.
  */
 export class TooltipController extends SlotController {
+  /**
+   * An HTML element for linking with the tooltip overlay
+   * via `aria-describedby` attribute used by screen readers.
+   * When not set, defaults to `target`.
+   */
+  ariaTarget: HTMLElement | HTMLElement[];
+
   /**
    * Object with properties passed to `generator`
    * function to be used for generating tooltip text.
@@ -51,6 +58,12 @@ export class TooltipController extends SlotController {
    */
   target: HTMLElement;
 
+  /**
+   * Set an HTML element for linking with the tooltip overlay
+   * via `aria-describedby` attribute used by screen readers.
+   */
+  setAriaTarget(ariaTarget: HTMLElement | HTMLElement[]): void;
+
   /**
    * Set a context object to be used by generator.
    */

package/src/tooltip-controller.js

@@ -26,6 +26,10 @@ export class TooltipController extends SlotController {
   initCustomNode(tooltipNode) {
     tooltipNode.target = this.target;
 
+    if (this.ariaTarget !== undefined) {
+      tooltipNode.ariaTarget = this.ariaTarget;
+    }
+
     if (this.context !== undefined) {
       tooltipNode.context = this.context;
     }
@@ -45,6 +49,33 @@ export class TooltipController extends SlotController {
     if (this.shouldShow !== undefined) {
       tooltipNode.shouldShow = this.shouldShow;
     }
+
+    this.__notifyChange();
+  }
+
+  /**
+   * Override to notify the host when the tooltip is removed.
+   *
+   * @param {Node} tooltipNode
+   * @protected
+   * @override
+   */
+  teardownNode() {
+    this.__notifyChange();
+  }
+
+  /**
+   * Set an HTML element for linking with the tooltip overlay
+   * via `aria-describedby` attribute used by screen readers.
+   * @param {HTMLElement} ariaTarget
+   */
+  setAriaTarget(ariaTarget) {
+    this.ariaTarget = ariaTarget;
+
+    const tooltipNode = this.node;
+    if (tooltipNode) {
+      tooltipNode.ariaTarget = ariaTarget;
+    }
   }
 
   /**
@@ -127,4 +158,9 @@ export class TooltipController extends SlotController {
       tooltipNode.target = target;
     }
   }
+
+  /** @private */
+  __notifyChange() {
+    this.dispatchEvent(new CustomEvent('tooltip-changed', { detail: { node: this.node } }));
+  }
 }

package/src/virtualizer-iron-list-adapter.js

@@ -82,10 +82,24 @@ export class IronListAdapter {
     return this.lastVisibleIndex + this._vidxOffset;
   }
 
+  __hasPlaceholders() {
+    return this.__getVisibleElements().some((el) => el.__virtualizerPlaceholder);
+  }
+
   scrollToIndex(index) {
     if (typeof index !== 'number' || isNaN(index) || this.size === 0 || !this.scrollTarget.offsetHeight) {
       return;
     }
+    delete this.__pendingScrollToIndex;
+
+    if (this._physicalCount <= 3 /* iron-list-core.DEFAULT_PHYSICAL_COUNT */) {
+      // The condition here is a performance improvement to avoid an unnecessary
+      // re-render when the physical item pool is already covered.
+
+      // Finish rendering at the current scroll position before scrolling
+      this.flush();
+    }
+
     index = this._clamp(index, 0, this.size - 1);
 
     const visibleElementCount = this.__getVisibleElements().length;
@@ -113,6 +127,12 @@ export class IronListAdapter {
       this._scrollTop -= this.__getIndexScrollOffset(index) || 0;
     }
     this._scrollHandler();
+
+    if (this.__hasPlaceholders()) {
+      // After rendering synchronously, there are still placeholders in the DOM.
+      // Try again after the next elements update.
+      this.__pendingScrollToIndex = index;
+    }
   }
 
   flush() {
@@ -199,8 +219,9 @@ export class IronListAdapter {
 
   __updateElement(el, index, forceSameIndexUpdates) {
     // Clean up temporary placeholder sizing
-    if (el.style.paddingTop) {
+    if (el.__virtualizerPlaceholder) {
       el.style.paddingTop = '';
+      el.__virtualizerPlaceholder = false;
     }
 
     if (!this.__preventElementUpdates && (el.__lastUpdatedIndex !== index || forceSameIndexUpdates)) {
@@ -224,6 +245,7 @@ export class IronListAdapter {
         // Assign a temporary placeholder sizing to elements that would otherwise end up having
         // no height.
         el.style.paddingTop = `${this.__placeholderHeight}px`;
+        el.__virtualizerPlaceholder = true;
 
         // Manually schedule the resize handler to make sure the placeholder padding is
         // cleared in case the resize observer never triggers.
@@ -241,6 +263,10 @@ export class IronListAdapter {
         this.__placeholderHeight = Math.round(filteredHeights.reduce((a, b) => a + b, 0) / filteredHeights.length);
       }
     });
+
+    if (this.__pendingScrollToIndex !== undefined && !this.__hasPlaceholders()) {
+      this.scrollToIndex(this.__pendingScrollToIndex);
+    }
   }
 
   __getIndexScrollOffset(index) {

package/src/data-provider-controller.js

@@ -1,126 +0,0 @@
-import { Cache } from './data-provider-controller/cache.js';
-import { getFlatIndexByPath, getFlatIndexInfo } from './data-provider-controller/helpers.js';
-
-export class DataProviderController extends EventTarget {
-  constructor(host, { size, pageSize, isExpanded, dataProvider, dataProviderParams }) {
-    super();
-    this.host = host;
-    this.size = size;
-    this.pageSize = pageSize;
-    this.isExpanded = isExpanded;
-    this.dataProvider = dataProvider;
-    this.dataProviderParams = dataProviderParams;
-    this.rootCache = this.#createRootCache();
-  }
-
-  get effectiveSize() {
-    return this.rootCache.effectiveSize;
-  }
-
-  isLoading() {
-    return this.rootCache.isLoading;
-  }
-
-  setSize(size) {
-    const delta = size - this.rootCache.size;
-    this.size = size;
-    this.rootCache.size += delta;
-    this.rootCache.effectiveSize += delta;
-  }
-
-  setPageSize(pageSize) {
-    this.pageSize = pageSize;
-    this.clearCache();
-  }
-
-  setDataProvider(dataProvider) {
-    this.dataProvider = dataProvider;
-    this.clearCache();
-  }
-
-  recalculateEffectiveSize() {
-    this.rootCache.recalculateEffectiveSize();
-  }
-
-  clearCache() {
-    this.rootCache = this.#createRootCache();
-  }
-
-  getFlatIndexInfo(flatIndex) {
-    return getFlatIndexInfo(this.rootCache, flatIndex);
-  }
-
-  getFlatIndexByPath(path) {
-    return getFlatIndexByPath(this.rootCache, path);
-  }
-
-  ensureFlatIndexLoaded(flatIndex) {
-    const { cache, page, item } = this.getFlatIndexInfo(flatIndex);
-
-    if (!item) {
-      this.#loadCachePage(cache, page);
-    }
-  }
-
-  ensureFlatIndexChildrenLoaded(flatIndex) {
-    const { cache, item, index } = this.getFlatIndexInfo(flatIndex);
-
-    if (item && this.isExpanded(item)) {
-      let subCache = cache.getSubCache(index);
-      if (!subCache) {
-        subCache = cache.createSubCache(index);
-      }
-
-      if (!subCache.isPageLoaded(0)) {
-        this.#loadCachePage(subCache, 0);
-      }
-    }
-  }
-
-  ensureFirstPageLoaded() {
-    if (!this.rootCache.isPageLoaded(0)) {
-      this.#loadCachePage(this.rootCache, 0);
-    }
-  }
-
-  #createRootCache() {
-    return new Cache(this, this.pageSize, this.size);
-  }
-
-  #loadCachePage(cache, page) {
-    if (!this.dataProvider || cache.pendingRequests.has(page)) {
-      return;
-    }
-
-    const params = {
-      page,
-      pageSize: this.pageSize,
-      parentItem: cache.parentItem,
-      ...this.dataProviderParams(),
-    };
-
-    const callback = (items, size) => {
-      if (size !== undefined) {
-        cache.size = size;
-      } else if (params.parentItem) {
-        cache.size = items.length;
-      }
-
-      cache.setPage(page, items);
-
-      this.recalculateEffectiveSize();
-
-      this.dispatchEvent(new CustomEvent('page-received'));
-
-      cache.pendingRequests.delete(page);
-
-      this.dispatchEvent(new CustomEvent('page-loaded'));
-    };
-
-    cache.pendingRequests.set(page, callback);
-
-    this.dispatchEvent(new CustomEvent('page-requested'));
-
-    this.dataProvider(params, callback);
-  }
-}