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

package/src/data-provider-controller/data-provider-controller.js

@@ -0,0 +1,248 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { Cache } from './cache.js';
+import { getFlatIndexByPath, getFlatIndexContext } from './helpers.js';
+
+/**
+ * A controller that stores and manages items loaded with a data provider.
+ */
+export class DataProviderController extends EventTarget {
+  /**
+   * The controller host element.
+   *
+   * @param {HTMLElement}
+   */
+  host;
+
+  /**
+   * A callback that returns data based on the passed params such as
+   * `page`, `pageSize`, `parentItem`, etc.
+   */
+  dataProvider;
+
+  /**
+   * A callback that returns additional params that need to be passed
+   * to the data provider callback with every request.
+   */
+  dataProviderParams;
+
+  /**
+   * A number of items in the root cache.
+   *
+   * @type {number}
+   */
+  size;
+
+  /**
+   * A number of items to display per page.
+   *
+   * @type {number}
+   */
+  pageSize;
+
+  /**
+   * A callback that returns whether the given item is expanded.
+   *
+   * @type {(item: unknown) => boolean}
+   */
+  isExpanded;
+
+  /**
+   * A reference to the root cache instance.
+   *
+   * @param {Cache}
+   */
+  rootCache;
+
+  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();
+  }
+
+  /**
+   * The total number of items, including items from expanded sub-caches.
+   */
+  get flatSize() {
+    return this.rootCache.flatSize;
+  }
+
+  /** @private */
+  get __cacheContext() {
+    return {
+      isExpanded: this.isExpanded,
+      // The controller instance is needed to ensure deprecated cache methods work.
+      __controller: this,
+    };
+  }
+
+  /**
+   * Whether the root cache or any of its decendant caches have pending requests.
+   *
+   * @return {boolean}
+   */
+  isLoading() {
+    return this.rootCache.isLoading;
+  }
+
+  /**
+   * Sets the size for the root cache and recalculates the flattened size.
+   *
+   * @param {number} size
+   */
+  setSize(size) {
+    this.size = size;
+    this.rootCache.size = size;
+    this.recalculateFlatSize();
+  }
+
+  /**
+   * Sets the page size and clears the cache.
+   *
+   * @param {number} pageSize
+   */
+  setPageSize(pageSize) {
+    this.pageSize = pageSize;
+    this.clearCache();
+  }
+
+  /**
+   * Sets the data provider callback and clears the cache.
+   *
+   * @type {Function}
+   */
+  setDataProvider(dataProvider) {
+    this.dataProvider = dataProvider;
+    this.clearCache();
+  }
+
+  /**
+   * Recalculates the flattened size.
+   */
+  recalculateFlatSize() {
+    this.rootCache.recalculateFlatSize();
+  }
+
+  /**
+   * Clears the cache.
+   */
+  clearCache() {
+    this.rootCache = this.__createRootCache();
+  }
+
+  /**
+   * Returns context for the given flattened index, including:
+   * - the corresponding cache
+   * - the associated item (if loaded)
+   * - the corresponding index in the cache's items array.
+   * - the page containing the index.
+   * - the cache level
+   */
+  getFlatIndexContext(flatIndex) {
+    return getFlatIndexContext(this.rootCache, flatIndex);
+  }
+
+  /**
+   * Returns the flattened index for the item that the given indexes point to.
+   * Each index in the path array points to a sub-item of the previous index.
+   * Using `Infinity` as an index will point to the last item on the level.
+   *
+   * @param {number[]} path
+   * @return {number}
+   */
+  getFlatIndexByPath(path) {
+    return getFlatIndexByPath(this.rootCache, path);
+  }
+
+  /**
+   * Requests the data provider to load the page with the item corresponding
+   * to the given flattened index. If the item is already loaded, the method
+   * returns immediatelly.
+   *
+   * @param {number} flatIndex
+   */
+  ensureFlatIndexLoaded(flatIndex) {
+    const { cache, page, item } = this.getFlatIndexContext(flatIndex);
+
+    if (!item) {
+      this.__loadCachePage(cache, page);
+    }
+  }
+
+  /**
+   * Creates a sub-cache for the item corresponding to the given flattened index and
+   * requests the data provider to load the first page into the created sub-cache.
+   * If the sub-cache already exists, the method returns immediatelly.
+   *
+   * @param {number} flatIndex
+   */
+  ensureFlatIndexHierarchy(flatIndex) {
+    const { cache, item, index } = this.getFlatIndexContext(flatIndex);
+
+    if (item && this.isExpanded(item) && !cache.getSubCache(index)) {
+      const subCache = cache.createSubCache(index);
+      this.__loadCachePage(subCache, 0);
+    }
+  }
+
+  /**
+   * Loads the first page into the root cache.
+   */
+  loadFirstPage() {
+    this.__loadCachePage(this.rootCache, 0);
+  }
+
+  /** @private */
+  __createRootCache() {
+    return new Cache(this.__cacheContext, this.pageSize, this.size);
+  }
+
+  /** @private */
+  __loadCachePage(cache, page) {
+    if (!this.dataProvider || cache.pendingRequests[page]) {
+      return;
+    }
+
+    let params = {
+      page,
+      pageSize: this.pageSize,
+      parentItem: cache.parentItem,
+    };
+
+    if (this.dataProviderParams) {
+      params = { ...params, ...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.recalculateFlatSize();
+
+      this.dispatchEvent(new CustomEvent('page-received'));
+
+      delete cache.pendingRequests[page];
+
+      this.dispatchEvent(new CustomEvent('page-loaded'));
+    };
+
+    cache.pendingRequests[page] = callback;
+
+    this.dispatchEvent(new CustomEvent('page-requested'));
+
+    this.dataProvider(params, callback);
+  }
+}

package/src/data-provider-controller/helpers.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * Returns context for the given flattened index, including:
+ * - the corresponding cache
+ * - the associated item (if loaded)
+ * - the corresponding index in the cache's items array.
+ * - the page containing the index.
+ * - the cache level
+ */
+export function getFlatIndexContext(
+  cache: Cache,
+  flatIndex: number,
+  level: number,
+): {
+  cache: Cache;
+  item: unknown | undefined;
+  index: number;
+  page: number;
+  level: number;
+};
+
+/**
+ * Recursively returns the globally flat index of the item the given indexes point to.
+ * Each index in the array points to a sub-item of the previous index.
+ * Using `Infinity` as an index will point to the last item on the level.
+ */
+export function getFlatIndexByPath(cache: Cache, path: number[], flatIndex: number): number;

package/src/data-provider-controller/helpers.js

@@ -1,5 +1,11 @@
 /**
- * Retreives information for the given flattened index, including:
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * Returns context for the given flattened index, including:
  * - the corresponding cache
  * - the associated item (if loaded)
  * - the corresponding index in the cache's items array.
@@ -10,16 +16,17 @@
  * @param {number} flatIndex
  * @return {{ cache: Cache, item: object | undefined, index: number, page: number, level: number }}
  */
-export function getFlatIndexInfo(cache, flatIndex, level = 0) {
+export function getFlatIndexContext(cache, flatIndex, level = 0) {
   let levelIndex = flatIndex;
 
-  for (const [index, subCache] of cache.subCaches) {
+  for (const subCache of cache.subCaches) {
+    const index = subCache.parentCacheIndex;
     if (levelIndex <= index) {
       break;
-    } else if (levelIndex <= index + subCache.effectiveSize) {
-      return getFlatIndexInfo(subCache, levelIndex - index - 1, level + 1);
+    } else if (levelIndex <= index + subCache.flatSize) {
+      return getFlatIndexContext(subCache, levelIndex - index - 1, level + 1);
     }
-    levelIndex -= subCache.effectiveSize;
+    levelIndex -= subCache.flatSize;
   }
 
   return {
@@ -36,8 +43,8 @@ export function getFlatIndexInfo(cache, flatIndex, level = 0) {
  * Each index in the array points to a sub-item of the previous index.
  * Using `Infinity` as an index will point to the last item on the level.
  *
- * @param {!ItemCache} cache
- * @param {!Array<number>} indexes
+ * @param {Cache} cache
+ * @param {number[]} path
  * @param {number} flatIndex
  * @return {number}
  */
@@ -49,7 +56,7 @@ export function getFlatIndexByPath(cache, [levelIndex, ...subIndexes], flatIndex
 
   const flatIndexOnLevel = cache.getFlatIndex(levelIndex);
   const subCache = cache.getSubCache(levelIndex);
-  if (subCache && subCache.effectiveSize > 0 && subIndexes.length) {
+  if (subCache && subCache.flatSize > 0 && subIndexes.length) {
     return getFlatIndexByPath(subCache, subIndexes, flatIndex + flatIndexOnLevel + 1);
   }
   return flatIndex + flatIndexOnLevel;

package/src/define.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+export interface CustomElementType extends CustomElementConstructor {
+  is: string;
+}
+
+export declare function defineCustomElement(CustomElement: CustomElementConstructor): void;

package/src/define.js

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+export function defineCustomElement(CustomElement) {
+  const defined = customElements.get(CustomElement.is);
+  if (!defined) {
+    Object.defineProperty(CustomElement, 'version', {
+      get() {
+        return '24.3.0-alpha2';
+      },
+    });
+
+    customElements.define(CustomElement.is, CustomElement);
+  } else {
+    const definedVersion = defined.version;
+    if (definedVersion && CustomElement.version && definedVersion === CustomElement.version) {
+      // Just loading the same thing again
+      console.warn(`The component ${CustomElement.is} has been loaded twice`);
+    } else {
+      console.error(
+        `Tried to define ${CustomElement.is} version ${CustomElement.version} when version ${defined.version} is already in use. Something will probably break.`,
+      );
+    }
+  }
+}

package/src/dom-utils.d.ts

@@ -13,6 +13,13 @@
  */
 export function getAncestorRootNodes(node: Node): Node[];
 
+/**
+ * Returns the list of flattened elements for the given `node`.
+ * This list consists of a node's children and, for any children that are
+ * `<slot>` elements, the expanded flattened list of `assignedElements`.
+ */
+export function getFlattenedElements(node: Node): Element[];
+
 /**
  * Traverses the given node and its parents, including those that are across
  * the shadow root boundaries, until it finds a node that matches the selector.

package/src/dom-utils.js

@@ -40,6 +40,27 @@ export function getAncestorRootNodes(node) {
   return result;
 }
 
+/**
+ * Returns the list of flattened elements for the given `node`.
+ * This list consists of a node's children and, for any children that are
+ * `<slot>` elements, the expanded flattened list of `assignedElements`.
+ *
+ * @param {Node} node
+ * @return {Element[]}
+ */
+export function getFlattenedElements(node) {
+  const result = [];
+  let elements;
+  if (node.localName === 'slot') {
+    elements = node.assignedElements();
+  } else {
+    result.push(node);
+    elements = [...node.children];
+  }
+  elements.forEach((elem) => result.push(...getFlattenedElements(elem)));
+  return result;
+}
+
 /**
  * Traverses the given node and its parents, including those that are across
  * the shadow root boundaries, until it finds a node that matches the selector.

package/src/element-mixin.d.ts

@@ -16,6 +16,7 @@ export declare function ElementMixin<T extends Constructor<HTMLElement>>(
 ): Constructor<DirMixinClass> & Constructor<ElementMixinClass> & T;
 
 export declare class ElementMixinClass {
+  static is: string;
   static version: string;
 
   protected static finalize(): void;

package/src/element-mixin.js

@@ -44,10 +44,6 @@ const registered = new Set();
  */
 export const ElementMixin = (superClass) =>
   class VaadinElementMixin extends DirMixin(superClass) {
-    static get version() {
-      return '24.2.0-alpha5';
-    }
-
     /** @protected */
     static finalize() {
       super.finalize();

package/src/overflow-controller.js

@@ -3,7 +3,6 @@
  * 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';
 import { animationFrame } from './async.js';
 import { Debouncer } from './debounce.js';
 
@@ -47,30 +46,41 @@ export class OverflowController {
    * @protected
    */
   observe() {
-    this.__resizeObserver = new ResizeObserver(() => {
+    const { host } = this;
+
+    this.__resizeObserver = new ResizeObserver((entries) => {
       this.__debounceOverflow = Debouncer.debounce(this.__debounceOverflow, animationFrame, () => {
         this.__updateOverflow();
       });
     });
 
-    this.__resizeObserver.observe(this.host);
+    this.__resizeObserver.observe(host);
 
-    this.__childObserver = new FlattenedNodesObserver(this.host, (info) => {
-      info.addedNodes.forEach((node) => {
-        if (node.nodeType === Node.ELEMENT_NODE) {
-          this.__resizeObserver.observe(node);
-        }
-      });
+    // Observe initial children
+    [...host.children].forEach((child) => {
+      this.__resizeObserver.observe(child);
+    });
 
-      info.removedNodes.forEach((node) => {
-        if (node.nodeType === Node.ELEMENT_NODE) {
-          this.__resizeObserver.unobserve(node);
-        }
+    this.__childObserver = new MutationObserver((mutations) => {
+      mutations.forEach(({ addedNodes, removedNodes }) => {
+        addedNodes.forEach((node) => {
+          if (node.nodeType === Node.ELEMENT_NODE) {
+            this.__resizeObserver.observe(node);
+          }
+        });
+
+        removedNodes.forEach((node) => {
+          if (node.nodeType === Node.ELEMENT_NODE) {
+            this.__resizeObserver.unobserve(node);
+          }
+        });
       });
 
       this.__updateOverflow();
     });
 
+    this.__childObserver.observe(host, { childList: true });
+
     // Update overflow attribute on scroll
     this.scrollTarget.addEventListener('scroll', this.__boundOnScroll);
 

package/src/path-utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright (c) 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * Convenience method for reading a value from a path.
+ */
+export function get(path: string, object: object): unknown;
+
+/**
+ * Convenience method for setting a value to a path.
+ */
+export function set(path: string, value: unknown, object: object): void;

package/src/path-utils.js

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright (c) 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * Convenience method for reading a value from a path.
+ *
+ * @param {string} path
+ * @param {object} object
+ */
+export function get(path, object) {
+  return path.split('.').reduce((obj, property) => (obj ? obj[property] : undefined), object);
+}
+
+/**
+ * Convenience method for setting a value to a path.
+ *
+ * @param {string} path
+ * @param {unknown} value
+ * @param {object} object
+ */
+export function set(path, value, object) {
+  const pathParts = path.split('.');
+  const lastPart = pathParts.pop();
+  const target = pathParts.reduce((target, part) => target[part], object);
+  target[lastPart] = value;
+}

package/src/polylit-mixin.js

@@ -4,6 +4,7 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { dedupeMixin } from '@open-wc/dedupe-mixin';
+import { get, set } from './path-utils.js';
 
 const caseMap = {};
 
@@ -92,15 +93,22 @@ const PolylitMixinImplementation = (superclass) => {
 
       let result = defaultDescriptor;
 
-      if ('value' in options) {
-        // Set the default value
-        this.addCheckedInitializer((instance) => {
-          if (typeof options.value === 'function') {
-            instance[name] = options.value.call(instance);
-          } else {
-            instance[name] = options.value;
-          }
-        });
+      if (options.sync) {
+        result = {
+          get: defaultDescriptor.get,
+          set(value) {
+            const oldValue = this[name];
+            this[key] = value;
+            this.requestUpdate(name, oldValue, options);
+
+            // Enforce synchronous update
+            if (this.hasUpdated) {
+              this.performUpdate();
+            }
+          },
+          configurable: true,
+          enumerable: true,
+        };
       }
 
       if (options.readOnly) {
@@ -110,6 +118,10 @@ const PolylitMixinImplementation = (superclass) => {
           // This is run during construction of the element
           instance[`_set${upper(name)}`] = function (value) {
             setter.call(instance, value);
+
+            if (options.sync) {
+              this.performUpdate();
+            }
           };
         });
 
@@ -123,6 +135,19 @@ const PolylitMixinImplementation = (superclass) => {
         };
       }
 
+      if ('value' in options) {
+        // Set the default value
+        this.addCheckedInitializer((instance) => {
+          const value = typeof options.value === 'function' ? options.value.call(instance) : options.value;
+
+          if (options.readOnly) {
+            instance[`_set${upper(name)}`](value);
+          } else {
+            instance[name] = value;
+          }
+        });
+      }
+
       if (options.observer) {
         const method = options.observer;
 
@@ -175,7 +200,7 @@ const PolylitMixinImplementation = (superclass) => {
         this.$ = {};
       }
 
-      this.shadowRoot.querySelectorAll('[id]').forEach((node) => {
+      this.renderRoot.querySelectorAll('[id]').forEach((node) => {
         this.$[node.id] = node;
       });
     }
@@ -202,8 +227,8 @@ const PolylitMixinImplementation = (superclass) => {
       }
 
       if (!this.__isReadyInvoked) {
-        this.ready();
         this.__isReadyInvoked = true;
+        this.ready();
       }
     }
 
@@ -254,15 +279,12 @@ const PolylitMixinImplementation = (superclass) => {
 
     /** @protected */
     _get(path, object) {
-      return path.split('.').reduce((obj, property) => (obj ? obj[property] : undefined), object);
+      return get(path, object);
     }
 
     /** @protected */
     _set(path, value, object) {
-      const pathParts = path.split('.');
-      const lastPart = pathParts.pop();
-      const target = pathParts.reduce((target, part) => target[part], object);
-      target[lastPart] = value;
+      set(path, value, object);
     }
   }
 

package/src/slot-controller.js

@@ -3,8 +3,8 @@
  * 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';
 import { isEmptyTextNode } from './dom-utils.js';
+import { SlotObserver } from './slot-observer.js';
 import { generateUniqueId } from './unique-id-utils.js';
 
 /**
@@ -199,17 +199,17 @@ export class SlotController extends EventTarget {
     const selector = slotName === '' ? 'slot:not([name])' : `slot[name=${slotName}]`;
     const slot = this.host.shadowRoot.querySelector(selector);
 
-    this.__slotObserver = new FlattenedNodesObserver(slot, (info) => {
+    this.__slotObserver = new SlotObserver(slot, ({ addedNodes, removedNodes }) => {
       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));
+      const newNodes = addedNodes.filter((node) => !isEmptyTextNode(node) && !current.includes(node));
 
-      if (info.removedNodes.length) {
-        this.nodes = current.filter((node) => !info.removedNodes.includes(node));
+      if (removedNodes.length) {
+        this.nodes = current.filter((node) => !removedNodes.includes(node));
 
-        info.removedNodes.forEach((node) => {
+        removedNodes.forEach((node) => {
           this.teardownNode(node);
         });
       }