@vaadin/component-base 24.2.0-alpha5 → 24.2.0-dev.f254716fe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/component-base",
-  "version": "24.2.0-alpha5",
+  "version": "24.2.0-dev.f254716fe",
   "publishConfig": {
     "access": "public"
   },
@@ -42,5 +42,5 @@
     "@vaadin/testing-helpers": "^0.4.3",
     "sinon": "^13.0.2"
   },
-  "gitHead": "73db22a5e8993e3ce48d1e6540d30eff9cb5c257"
+  "gitHead": "da54950b9f8c14c6451ede0d426e16a489c7fb9b"
 }

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

@@ -0,0 +1,226 @@
+export class Cache {
+  /**
+   * @type {import('../data-provider-controller.js').DataProviderController}
+   */
+  controller;
+
+  /**
+   * The number of items.
+   *
+   * @type {number}
+   */
+  size = 0;
+
+  /**
+   * The number of items to display per page.
+   *
+   * @type {number}
+   */
+  pageSize;
+
+  /**
+   * The total number of items, including items from expanded sub-caches.
+   *
+   * @type {number}
+   */
+  effectiveSize = 0;
+
+  /**
+   * An array of cached items.
+   *
+   * @type {object[]}
+   */
+  items = [];
+
+  /**
+   * A map where the key is a requested page and the value is a callback
+   * that will be called with data once the request is complete.
+   *
+   * @type {Map<number, Function>}
+   */
+  pendingRequests = new Map();
+
+  /**
+   * A map where the key is the index of an item in the `items` array
+   * and the value is a sub-cache associated with that item.
+   *
+   * Note, it's intentionally defined as an object instead of a Map
+   * to ensure that Object.entries() returns an array with keys sorted
+   * in alphabetical order, rather than the order they were added.
+   *
+   * @type {Record<number, Cache>}
+   */
+  #subCacheByIndex = {};
+
+  /**
+   * @param {Cache['controller']} controller
+   * @param {number} pageSize
+   * @param {number | undefined} size
+   * @param {Cache | undefined} parentCache
+   * @param {number | undefined} parentCacheIndex
+   */
+  constructor(controller, pageSize, size, parentCache, parentCacheIndex) {
+    this.controller = controller;
+    this.pageSize = pageSize;
+    this.size = size || 0;
+    this.effectiveSize = size || 0;
+    this.parentCache = parentCache;
+    this.parentCacheIndex = parentCacheIndex;
+  }
+
+  /**
+   * An item in the parent cache that the current cache is associated with.
+   *
+   * @return {object | undefined}
+   */
+  get parentItem() {
+    return this.parentCache && this.parentCache.items[this.parentCacheIndex];
+  }
+
+  /**
+   * Whether the cache or any of its descendant caches have pending requests.
+   *
+   * @return {boolean}
+   */
+  get isLoading() {
+    if (this.pendingRequests.size > 0) {
+      return true;
+    }
+
+    return Object.values(this.#subCacheByIndex).some((subCache) => subCache.isLoading);
+  }
+
+  /**
+   * An array of sub-caches sorted in the same order as their associated items
+   * appear in the `items` array.
+   *
+   * @return {Array<[number, Cache]>}
+   */
+  get subCaches() {
+    return Object.entries(this.#subCacheByIndex).map(([index, subCache]) => {
+      return [parseInt(index), subCache];
+    });
+  }
+
+  /**
+   * Recalculates the effective size for the cache and its descendant caches recursively.
+   */
+  recalculateEffectiveSize() {
+    this.effectiveSize =
+      !this.parentItem || this.controller.isExpanded(this.parentItem)
+        ? this.size +
+          Object.values(this.#subCacheByIndex).reduce((total, subCache) => {
+            subCache.recalculateEffectiveSize();
+            return total + subCache.effectiveSize;
+          }, 0)
+        : 0;
+  }
+
+  /**
+   * Adds an array of items corresponding to the given page
+   * to the `items` array.
+   *
+   * @param {number} page
+   * @param {object[]} items
+   */
+  setPage(page, items) {
+    const startIndex = page * this.pageSize;
+    items.forEach((item, i) => {
+      this.items[startIndex + i] = item;
+    });
+  }
+
+  /**
+   * Returns whether the given page has been loaded in the cache.
+   *
+   * @param {number} page
+   * @return {boolean}
+   */
+  isPageLoaded(page) {
+    return this.items[page * this.pageSize] !== undefined;
+  }
+
+  /**
+   * Retrieves the sub-cache associated with the item at the given index
+   * in the `items` array.
+   *
+   * @param {number} index
+   * @return {Cache | undefined}
+   */
+  getSubCache(index) {
+    return this.#subCacheByIndex[index];
+  }
+
+  /**
+   * Removes the sub-cache associated with the item at the given index
+   * in the `items` array.
+   *
+   * @param {number} index
+   */
+  removeSubCache(index) {
+    const subCache = this.getSubCache(index);
+    delete this.#subCacheByIndex[index];
+
+    this.controller.dispatchEvent(
+      new CustomEvent('sub-cache-removed', {
+        detail: {
+          cache: this,
+          subCache,
+        },
+      }),
+    );
+  }
+
+  /**
+   * Removes all sub-caches.
+   */
+  removeSubCaches() {
+    this.#subCacheByIndex = {};
+
+    this.controller.dispatchEvent(
+      new CustomEvent('sub-caches-removed', {
+        detail: {
+          cache: this,
+        },
+      }),
+    );
+  }
+
+  /**
+   * Creates and associates a sub-cache for the item at the given index
+   * in the `items` array.
+   *
+   * @param {number} index
+   * @return {Cache}
+   */
+  createSubCache(index) {
+    const subCache = new Cache(this.controller, this.pageSize, 0, this, index);
+    this.#subCacheByIndex[index] = subCache;
+
+    this.controller.dispatchEvent(
+      new CustomEvent('sub-cache-created', {
+        detail: {
+          cache: this,
+          subCache,
+        },
+      }),
+    );
+
+    return subCache;
+  }
+
+  /**
+   * Retrieves the flattened index corresponding to the given index
+   * of an item in the `items` array.
+   *
+   * @param {number} index
+   * @return {number}
+   */
+  getFlatIndex(index) {
+    const clampedIndex = Math.max(0, Math.min(this.size - 1, index));
+
+    return this.subCaches.reduce((prev, [index, subCache]) => {
+      return clampedIndex > index ? prev + subCache.effectiveSize : prev;
+    }, clampedIndex);
+  }
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Retreives information 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
+ *
+ * @param {import('./cache.js').Cache} cache
+ * @param {number} flatIndex
+ * @return {{ cache: Cache, item: object | undefined, index: number, page: number, level: number }}
+ */
+export function getFlatIndexInfo(cache, flatIndex, level = 0) {
+  let levelIndex = flatIndex;
+
+  for (const [index, subCache] of cache.subCaches) {
+    if (levelIndex <= index) {
+      break;
+    } else if (levelIndex <= index + subCache.effectiveSize) {
+      return getFlatIndexInfo(subCache, levelIndex - index - 1, level + 1);
+    }
+    levelIndex -= subCache.effectiveSize;
+  }
+
+  return {
+    cache,
+    item: cache.items[levelIndex],
+    index: levelIndex,
+    page: Math.floor(levelIndex / cache.pageSize),
+    level,
+  };
+}
+
+/**
+ * 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.
+ *
+ * @param {!ItemCache} cache
+ * @param {!Array<number>} indexes
+ * @param {number} flatIndex
+ * @return {number}
+ */
+export function getFlatIndexByPath(cache, [levelIndex, ...subIndexes], flatIndex = 0) {
+  if (levelIndex === Infinity) {
+    // Treat Infinity as the last index on the level
+    levelIndex = cache.size - 1;
+  }
+
+  const flatIndexOnLevel = cache.getFlatIndex(levelIndex);
+  const subCache = cache.getSubCache(levelIndex);
+  if (subCache && subCache.effectiveSize > 0 && subIndexes.length) {
+    return getFlatIndexByPath(subCache, subIndexes, flatIndex + flatIndexOnLevel + 1);
+  }
+  return flatIndex + flatIndexOnLevel;
+}

package/src/data-provider-controller.js

@@ -0,0 +1,126 @@
+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);
+  }
+}