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

package/index.d.ts

@@ -4,3 +4,4 @@ export { DirMixin } from './src/dir-mixin.js';
 export { ElementMixin } from './src/element-mixin.js';
 export { ResizeMixin } from './src/resize-mixin.js';
 export { SlotController } from './src/slot-controller.js';
+export { SlotStylesMixin } from './src/slot-styles-mixin.js';

package/index.js

@@ -4,3 +4,4 @@ export { DirMixin } from './src/dir-mixin.js';
 export { ElementMixin } from './src/element-mixin.js';
 export { ResizeMixin } from './src/resize-mixin.js';
 export { SlotController } from './src/slot-controller.js';
+export { SlotStylesMixin } from './src/slot-styles-mixin.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/component-base",
-  "version": "24.2.0-dev.f254716fe",
+  "version": "24.3.0-alpha2",
   "publishConfig": {
     "access": "public"
   },
@@ -39,8 +39,8 @@
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/testing-helpers": "^0.4.3",
+    "@vaadin/testing-helpers": "^0.5.0",
     "sinon": "^13.0.2"
   },
-  "gitHead": "da54950b9f8c14c6451ede0d426e16a489c7fb9b"
+  "gitHead": "0fd437292fa2a2f65e29b424d2456909ad2d684b"
 }

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

@@ -0,0 +1,146 @@
+/**
+ * @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 { DataProviderCallback } from './data-provider-controller.js';
+
+export type CacheContext<TItem> = { isExpanded(item: TItem): boolean };
+
+/**
+ * A class that stores items with their associated sub-caches.
+ */
+export class Cache<TItem> {
+  /**
+   * A context object.
+   */
+  context: CacheContext<TItem>;
+
+  /**
+   * The number of items.
+   */
+  size: number;
+
+  /**
+   * The number of items to display per page.
+   */
+  pageSize: number;
+
+  /**
+   * An array of cached items.
+   */
+  items: TItem[];
+
+  /**
+   * 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.
+   */
+  pendingRequests: Record<number, DataProviderCallback<TItem>>;
+
+  /**
+   * An item in the parent cache that the current cache is associated with.
+   */
+  get parentItem(): TItem | undefined;
+
+  /**
+   * An array of sub-caches sorted in the same order as their associated items
+   * appear in the `items` array.
+   */
+  get subCaches(): Array<Cache<TItem>>;
+
+  /**
+   * Whether the cache or any of its descendant caches have pending requests.
+   */
+  get isLoading(): boolean;
+
+  /**
+   * The total number of items, including items from expanded sub-caches.
+   */
+  get flatSize(): number;
+
+  /**
+   * The total number of items, including items from expanded sub-caches.
+   *
+   * @protected
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  get effectiveSize(): number;
+
+  constructor(
+    context: CacheContext<TItem>,
+    pageSize: number,
+    size: number,
+    parentCache?: Cache<TItem>,
+    parentCacheIndex?: number,
+  );
+
+  /**
+   * Recalculates the flattened size for the cache and its descendant caches recursively.
+   */
+  recalculateFlatSize(): void;
+
+  /**
+   * Adds an array of items corresponding to the given page
+   * to the `items` array.
+   */
+  setPage(page: number, items: unknown[]): void;
+
+  /**
+   * Retrieves the sub-cache associated with the item at the given index
+   * in the `items` array.
+   */
+  getSubCache(index: number): Cache<TItem> | undefined;
+
+  /**
+   * Removes the sub-cache associated with the item at the given index
+   * in the `items` array.
+   */
+  removeSubCache(index: number): void;
+
+  /**
+   * Removes all sub-caches.
+   */
+  removeSubCaches(): void;
+
+  /**
+   * Creates and associates a sub-cache for the item at the given index
+   * in the `items` array.
+   */
+  createSubCache(index: number): Cache<TItem>;
+
+  /**
+   * Retrieves the flattened index corresponding to the given index
+   * of an item in the `items` array.
+   */
+  getFlatIndex(index: number): number;
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  getItemForIndex(index: number): TItem | undefined;
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  getCacheAndIndex(index: number): { cache: Cache<TItem>; scaledIndex: number };
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  updateSize(): void;
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  ensureSubCacheForScaledIndex(scaledIndex: number): void;
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  get grid(): HTMLElement;
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  get itemCaches(): object;
+}

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

@@ -1,8 +1,20 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { getFlatIndexContext } from './helpers.js';
+
+/**
+ * A class that stores items with their associated sub-caches.
+ */
 export class Cache {
   /**
-   * @type {import('../data-provider-controller.js').DataProviderController}
+   * A context object.
+   *
+   * @type {{ isExpanded: (item: unknown) => boolean }}
    */
-  controller;
+  context;
 
   /**
    * The number of items.
@@ -18,13 +30,6 @@ export class Cache {
    */
   pageSize;
 
-  /**
-   * The total number of items, including items from expanded sub-caches.
-   *
-   * @type {number}
-   */
-  effectiveSize = 0;
-
   /**
    * An array of cached items.
    *
@@ -36,9 +41,9 @@ export class Cache {
    * 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>}
+   * @type {Record<number, Function>}
    */
-  pendingRequests = new Map();
+  pendingRequests = {};
 
   /**
    * A map where the key is the index of an item in the `items` array
@@ -49,23 +54,32 @@ export class Cache {
    * in alphabetical order, rather than the order they were added.
    *
    * @type {Record<number, Cache>}
+   * @private
    */
-  #subCacheByIndex = {};
+  __subCacheByIndex = {};
 
   /**
-   * @param {Cache['controller']} controller
+   * The total number of items, including items from expanded sub-caches.
+   *
+   * @type {number}
+   * @private
+   */
+  __flatSize = 0;
+
+  /**
+   * @param {Cache['context']} context
    * @param {number} pageSize
    * @param {number | undefined} size
    * @param {Cache | undefined} parentCache
    * @param {number | undefined} parentCacheIndex
    */
-  constructor(controller, pageSize, size, parentCache, parentCacheIndex) {
-    this.controller = controller;
+  constructor(context, pageSize, size, parentCache, parentCacheIndex) {
+    this.context = context;
     this.pageSize = pageSize;
     this.size = size || 0;
-    this.effectiveSize = size || 0;
     this.parentCache = parentCache;
     this.parentCacheIndex = parentCacheIndex;
+    this.__flatSize = size || 0;
   }
 
   /**
@@ -77,41 +91,61 @@ export class Cache {
     return this.parentCache && this.parentCache.items[this.parentCacheIndex];
   }
 
+  /**
+   * An array of sub-caches sorted in the same order as their associated items
+   * appear in the `items` array.
+   *
+   * @return {Cache[]}
+   */
+  get subCaches() {
+    return Object.values(this.__subCacheByIndex);
+  }
+
   /**
    * Whether the cache or any of its descendant caches have pending requests.
    *
    * @return {boolean}
    */
   get isLoading() {
-    if (this.pendingRequests.size > 0) {
+    if (Object.keys(this.pendingRequests).length > 0) {
       return true;
     }
 
-    return Object.values(this.#subCacheByIndex).some((subCache) => subCache.isLoading);
+    return this.subCaches.some((subCache) => subCache.isLoading);
   }
 
   /**
-   * An array of sub-caches sorted in the same order as their associated items
-   * appear in the `items` array.
+   * The total number of items, including items from expanded sub-caches.
    *
-   * @return {Array<[number, Cache]>}
+   * @return {number}
    */
-  get subCaches() {
-    return Object.entries(this.#subCacheByIndex).map(([index, subCache]) => {
-      return [parseInt(index), subCache];
-    });
+  get flatSize() {
+    return this.__flatSize;
   }
 
   /**
-   * Recalculates the effective size for the cache and its descendant caches recursively.
+   * The total number of items, including items from expanded sub-caches.
+   *
+   * @protected
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
    */
-  recalculateEffectiveSize() {
-    this.effectiveSize =
-      !this.parentItem || this.controller.isExpanded(this.parentItem)
+  get effectiveSize() {
+    console.warn(
+      '<vaadin-grid> The `effectiveSize` property of ItemCache is deprecated and will be removed in Vaadin 25.',
+    );
+    return this.flatSize;
+  }
+
+  /**
+   * Recalculates the flattened size for the cache and its descendant caches recursively.
+   */
+  recalculateFlatSize() {
+    this.__flatSize =
+      !this.parentItem || this.context.isExpanded(this.parentItem)
         ? this.size +
-          Object.values(this.#subCacheByIndex).reduce((total, subCache) => {
-            subCache.recalculateEffectiveSize();
-            return total + subCache.effectiveSize;
+          this.subCaches.reduce((total, subCache) => {
+            subCache.recalculateFlatSize();
+            return total + subCache.flatSize;
           }, 0)
         : 0;
   }
@@ -130,16 +164,6 @@ export class Cache {
     });
   }
 
-  /**
-   * 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.
@@ -148,7 +172,7 @@ export class Cache {
    * @return {Cache | undefined}
    */
   getSubCache(index) {
-    return this.#subCacheByIndex[index];
+    return this.__subCacheByIndex[index];
   }
 
   /**
@@ -158,32 +182,14 @@ export class Cache {
    * @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,
-        },
-      }),
-    );
+    delete this.__subCacheByIndex[index];
   }
 
   /**
    * Removes all sub-caches.
    */
   removeSubCaches() {
-    this.#subCacheByIndex = {};
-
-    this.controller.dispatchEvent(
-      new CustomEvent('sub-caches-removed', {
-        detail: {
-          cache: this,
-        },
-      }),
-    );
+    this.__subCacheByIndex = {};
   }
 
   /**
@@ -194,18 +200,8 @@ export class Cache {
    * @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,
-        },
-      }),
-    );
-
+    const subCache = new Cache(this.context, this.pageSize, 0, this, index);
+    this.__subCacheByIndex[index] = subCache;
     return subCache;
   }
 
@@ -219,8 +215,71 @@ export class Cache {
   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;
+    return this.subCaches.reduce((prev, subCache) => {
+      const index = subCache.parentCacheIndex;
+      return clampedIndex > index ? prev + subCache.flatSize : prev;
     }, clampedIndex);
   }
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  getItemForIndex(index) {
+    console.warn(
+      '<vaadin-grid> The `getItemForIndex` method of ItemCache is deprecated and will be removed in Vaadin 25.',
+    );
+    const { item } = getFlatIndexContext(this, index);
+    return item;
+  }
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  getCacheAndIndex(index) {
+    console.warn(
+      '<vaadin-grid> The `getCacheAndIndex` method of ItemCache is deprecated and will be removed in Vaadin 25.',
+    );
+    const { cache, index: scaledIndex } = getFlatIndexContext(this, index);
+    return { cache, scaledIndex };
+  }
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  updateSize() {
+    console.warn('<vaadin-grid> The `updateSize` method of ItemCache is deprecated and will be removed in Vaadin 25.');
+    this.recalculateFlatSize();
+  }
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  ensureSubCacheForScaledIndex(scaledIndex) {
+    console.warn(
+      '<vaadin-grid> The `ensureSubCacheForScaledIndex` method of ItemCache is deprecated and will be removed in Vaadin 25.',
+    );
+
+    if (!this.getSubCache(scaledIndex)) {
+      const subCache = this.createSubCache(scaledIndex);
+      this.context.__controller.__loadCachePage(subCache, 0);
+    }
+  }
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  get grid() {
+    console.warn('<vaadin-grid> The `grid` property of ItemCache is deprecated and will be removed in Vaadin 25.');
+    return this.context.__controller.host;
+  }
+
+  /**
+   * @deprecated since 24.3 and will be removed in Vaadin 25.
+   */
+  get itemCaches() {
+    console.warn(
+      '<vaadin-grid> The `itemCaches` property of ItemCache is deprecated and will be removed in Vaadin 25.',
+    );
+    return this.__subCacheByIndex;
+  }
 }

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

@@ -0,0 +1,156 @@
+/**
+ * @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 { ReactiveController } from 'lit';
+import type { Cache } from './cache.js';
+
+type DataProviderDefaultParams = {
+  page: number;
+  pageSize: number;
+  parentItem?: unknown;
+};
+
+export type DataProviderCallback<TItem> = (items: TItem[], size?: number) => void;
+
+export type DataProvider<TItem, TDataProviderParams extends Record<string, unknown>> = (
+  params: DataProviderDefaultParams & TDataProviderParams,
+  callback: DataProviderCallback<TItem>,
+) => void;
+
+/**
+ * A controller that stores and manages items loaded with a data provider.
+ */
+export class DataProviderController<TItem, TDataProviderParams extends Record<string, unknown>>
+  implements ReactiveController
+{
+  /**
+   * The controller host element.
+   */
+  host: HTMLElement;
+
+  /**
+   * A callback that returns data based on the passed params such as
+   * `page`, `pageSize`, `parentItem`, etc.
+   */
+  dataProvider: DataProvider<TItem, TDataProviderParams>;
+
+  /**
+   * A callback that returns additional params that need to be passed
+   * to the data provider callback with every request.
+   */
+  dataProviderParams: () => TDataProviderParams;
+
+  /**
+   * A number of items in the root cache.
+   */
+  size?: number;
+
+  /**
+   * A number of items to display per page.
+   */
+  pageSize: number;
+
+  /**
+   * A callback that returns whether the given item is expanded.
+   */
+  isExpanded: (item: TItem) => boolean;
+
+  /**
+   * A reference to the root cache instance.
+   */
+  rootCache: Cache<TItem>;
+
+  constructor(
+    host: HTMLElement,
+    config: {
+      size?: number;
+      pageSize: number;
+      isExpanded(item: TItem): boolean;
+      dataProvider: DataProvider<TItem, TDataProviderParams>;
+      dataProviderParams(): TDataProviderParams;
+    },
+  );
+
+  /**
+   * The total number of items, including items from expanded sub-caches.
+   */
+  get flatSize(): number;
+
+  hostConnected(): void;
+
+  hostDisconnected(): void;
+
+  /**
+   * Whether the root cache or any of its decendant caches have pending requests.
+   */
+  isLoading(): boolean;
+
+  /**
+   * Sets the size for the root cache and recalculates the flattened size.
+   */
+  setSize(size: number): void;
+
+  /**
+   * Sets the page size and clears the cache.
+   */
+  setPageSize(pageSize: number): void;
+
+  /**
+   * Sets the data provider callback and clears the cache.
+   */
+  setDataProvider(dataProvider: DataProvider<TItem, TDataProviderParams>): void;
+
+  /**
+   * Recalculates the flattened size.
+   */
+  recalculateFlatSize(): void;
+
+  /**
+   * Clears the cache.
+   */
+  clearCache(): void;
+
+  /**
+   * 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: number): {
+    cache: Cache<TItem>;
+    item: TItem | undefined;
+    index: number;
+    page: number;
+    level: number;
+  };
+
+  /**
+   * 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.
+   */
+  getFlatIndexByPath(path: number[]): number;
+
+  /**
+   * 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.
+   */
+  ensureFlatIndexLoaded(flatIndex: number): void;
+
+  /**
+   * 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.
+   */
+  ensureFlatIndexHierarchy(flatIndex: number): void;
+
+  /**
+   * Loads the first page into the root cache.
+   */
+  loadFirstPage(): void;
+}