feat: add getItemContext method to DataProviderController (#6613)

packages/component-base/src/data-provider-controller/data-provider-controller.d.ts

@@ -5,6 +5,7 @@
  */
 import type { ReactiveController } from 'lit';
 import type { Cache } from './cache.js';
+import type { getFlatIndexByPath, getFlatIndexContext, getItemContext } from './helpers.js';
 
 type DataProviderDefaultParams = {
   page: number;
@@ -57,6 +58,12 @@ export class DataProviderController<TItem, TDataProviderParams extends Record<st
    */
   isExpanded: (item: TItem) => boolean;
 
+  /**
+   * A callback that returns the id for the given item and that
+   * is used when checking object items for equality.
+   */
+  getItemId: (item: TItem) => unknown;
+
   /**
    * A reference to the root cache instance.
    */
@@ -67,6 +74,7 @@ export class DataProviderController<TItem, TDataProviderParams extends Record<st
     config: {
       size?: number;
       pageSize: number;
+      getItemId(item: TItem): unknown;
       isExpanded(item: TItem): boolean;
       dataProvider: DataProvider<TItem, TDataProviderParams>;
       dataProviderParams(): TDataProviderParams;
@@ -115,25 +123,33 @@ export class DataProviderController<TItem, TDataProviderParams extends Record<st
   /**
    * 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
+   * - the corresponding item (if loaded)
+   * - the item's index in the cache's items array
+   * - the page containing the item
+   */
+  getFlatIndexContext(flatIndex: number): ReturnType<typeof getFlatIndexContext<TItem>>;
+
+  /**
+   * Returns context for the given item, including:
+   * - the cache containing the item
+   * - the cache level
+   * - the item
+   * - the item's index in the cache's items array
+   * - the item's flattened index
+   * - the item's sub-cache (if exists)
+   * - the page containing the item
+   *
+   * If the item isn't found, the method returns undefined.
    */
-  getFlatIndexContext(flatIndex: number): {
-    cache: Cache<TItem>;
-    item: TItem | undefined;
-    index: number;
-    page: number;
-    level: number;
-  };
+  getItemContext(item: TItem): ReturnType<typeof getItemContext<TItem>>;
 
   /**
    * 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;
+  getFlatIndexByPath(path: number[]): ReturnType<typeof getFlatIndexByPath<TItem>>;
 
   /**
    * Requests the data provider to load the page with the item corresponding

packages/component-base/src/data-provider-controller/data-provider-controller.js

@@ -4,7 +4,7 @@
  * 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';
+import { getFlatIndexByPath, getFlatIndexContext, getItemContext } from './helpers.js';
 
 /**
  * A controller that stores and manages items loaded with a data provider.
@@ -50,18 +50,27 @@ export class DataProviderController extends EventTarget {
    */
   isExpanded;
 
+  /**
+   * A callback that returns the id for the given item and that
+   * is used when checking object items for equality.
+   *
+   * @type { (item: unknown) => unknown}
+   */
+  getItemId;
+
   /**
    * A reference to the root cache instance.
    *
    * @param {Cache}
    */
   rootCache;
 
-  constructor(host, { size, pageSize, isExpanded, dataProvider, dataProviderParams }) {
+  constructor(host, { size, pageSize, isExpanded, getItemId, dataProvider, dataProviderParams }) {
     super();
     this.host = host;
     this.size = size;
     this.pageSize = pageSize;
+    this.getItemId = getItemId;
     this.isExpanded = isExpanded;
     this.dataProvider = dataProvider;
     this.dataProviderParams = dataProviderParams;
@@ -141,15 +150,33 @@ export class DataProviderController extends EventTarget {
   /**
    * 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
+   * - the corresponding item (if loaded)
+   * - the item's index in the cache's items array
+   * - the page containing the item
+   *
+   * @param {number} flatIndex
    */
   getFlatIndexContext(flatIndex) {
     return getFlatIndexContext(this.rootCache, flatIndex);
   }
 
+  /**
+   * Returns context for the given item, including:
+   * - the cache containing the item
+   * - the cache level
+   * - the item
+   * - the item's index in the cache's items array
+   * - the item's flattened index
+   * - the item's sub-cache (if exists)
+   * - the page containing the item
+   *
+   * If the item isn't found, the method returns undefined.
+   */
+  getItemContext(item) {
+    return getItemContext({ getItemId: this.getItemId }, this.rootCache, item);
+  }
+
   /**
    * 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.

packages/component-base/src/data-provider-controller/helpers.d.ts

@@ -3,30 +3,61 @@
  * Copyright (c) 2021 - 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
+import type { Cache } from './cache.js';
 
 /**
  * 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
+ * - the corresponding item (if loaded)
+ * - the item's index in the cache's items array
+ * - the page containing the item
  */
-export function getFlatIndexContext(
-  cache: Cache,
+export function getFlatIndexContext<TItem>(
+  cache: Cache<TItem>,
   flatIndex: number,
   level: number,
 ): {
-  cache: Cache;
-  item: unknown | undefined;
+  cache: Cache<TItem>;
+  item: TItem | undefined;
   index: number;
   page: number;
   level: number;
 };
 
+/**
+ * Returns context for the given item, including:
+ * - the cache containing the item
+ * - the cache level
+ * - the item
+ * - the item's index in the cache's items array
+ * - the item's flattened index
+ * - the item's sub-cache (if exists)
+ * - the page containing the item
+ *
+ * If the item isn't found, the method returns undefined.
+ */
+export function getItemContext<TItem>(
+  context: { getItemId(item: TItem): unknown },
+  cache: Cache<TItem>,
+  targetItem: TItem,
+  level: number,
+  levelFlatIndex: number,
+):
+  | {
+      level: number;
+      item: TItem;
+      index: number;
+      page: number;
+      flatIndex: number;
+      cache: Cache<TItem>;
+      subCache: Cache<TItem> | undefined;
+    }
+  | undefined;
+
 /**
  * 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;
+export function getFlatIndexByPath<TItem>(cache: Cache<TItem>, path: number[], flatIndex: number): number;

packages/component-base/src/data-provider-controller/helpers.js

@@ -4,17 +4,20 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 
+/**
+ * @typedef {import('./cache.js').Cache} Cache
+ */
+
 /**
  * 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
+ * - the corresponding item (if loaded)
+ * - the item's index in the cache's items array
+ * - the page containing the item
  *
- * @param {import('./cache.js').Cache} cache
+ * @param {Cache} cache
  * @param {number} flatIndex
- * @return {{ cache: Cache, item: object | undefined, index: number, page: number, level: number }}
  */
 export function getFlatIndexContext(cache, flatIndex, level = 0) {
   let levelIndex = flatIndex;
@@ -38,6 +41,52 @@ export function getFlatIndexContext(cache, flatIndex, level = 0) {
   };
 }
 
+/**
+ * Returns context for the given item, including:
+ * - the cache containing the item
+ * - the cache level
+ * - the item
+ * - the item's index in the cache's items array
+ * - the item's flattened index
+ * - the item's sub-cache (if exists)
+ * - the page containing the item
+ *
+ * If the item isn't found, the method returns undefined.
+ *
+ * @param {Cache} cache
+ * @param {{ getItemId: (item: unknown) => unknown}} context
+ * @param {Cache} cache
+ * @param {unknown} targetItem
+ * @param {number} level
+ * @param {number} levelFlatIndex
+ */
+export function getItemContext({ getItemId }, cache, targetItem, level = 0, levelFlatIndex = 0) {
+  // Start looking in this cache
+  for (let index = 0; index < cache.items.length; index++) {
+    const item = cache.items[index];
+    if (!!item && getItemId(item) === getItemId(targetItem)) {
+      return {
+        cache,
+        level,
+        item,
+        index,
+        page: Math.floor(index / cache.pageSize),
+        subCache: cache.getSubCache(index),
+        flatIndex: levelFlatIndex + cache.getFlatIndex(index),
+      };
+    }
+  }
+
+  // Look through sub-caches
+  for (const subCache of cache.subCaches) {
+    const parentItemFlatIndex = levelFlatIndex + cache.getFlatIndex(subCache.parentCacheIndex);
+    const result = getItemContext({ getItemId }, subCache, targetItem, level + 1, parentItemFlatIndex + 1);
+    if (result) {
+      return result;
+    }
+  }
+}
+
 /**
  * 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.

packages/component-base/test/data-provider-controller-helpers.js

@@ -1,6 +1,8 @@
-export function createDataProvider({ size, async }) {
+export function createDataProvider({ size, async, generator }) {
+  generator ||= (parentItem, i) => `${parentItem ?? 'Item'}-${i}`;
+
   return ({ page, pageSize, parentItem }, callback) => {
-    const items = Array.from({ length: size }, (_, i) => `${parentItem ?? 'Item'}-${i}`);
+    const items = Array.from({ length: size }, (_, i) => generator(parentItem, i));
     const result = items.splice(page * pageSize, pageSize);
 
     if (async) {