@vaadin/component-base 24.3.0-alpha1 → 24.3.0-alpha11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/component-base",
-  "version": "24.3.0-alpha1",
+  "version": "24.3.0-alpha11",
   "publishConfig": {
     "access": "public"
   },
@@ -35,12 +35,12 @@
     "@polymer/polymer": "^3.0.0",
     "@vaadin/vaadin-development-mode-detector": "^2.0.0",
     "@vaadin/vaadin-usage-statistics": "^2.1.0",
-    "lit": "^2.0.0"
+    "lit": "^3.0.0"
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/testing-helpers": "^0.5.0",
+    "@vaadin/testing-helpers": "^0.6.0",
     "sinon": "^13.0.2"
   },
-  "gitHead": "9ca6f3ca220a777e8eea181a1f5717e39a732240"
+  "gitHead": "123cf569a1b6ef6f4ef5fe8e60cb8d988699b98c"
 }

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

@@ -3,12 +3,15 @@
  * 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 {
   /**
+   * A context object.
+   *
    * @type {{ isExpanded: (item: unknown) => boolean }}
    */
   context;
@@ -38,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
@@ -61,7 +64,7 @@ export class Cache {
    * @type {number}
    * @private
    */
-  __effectiveSize = 0;
+  __flatSize = 0;
 
   /**
    * @param {Cache['context']} context
@@ -76,7 +79,7 @@ export class Cache {
     this.size = size || 0;
     this.parentCache = parentCache;
     this.parentCacheIndex = parentCacheIndex;
-    this.__effectiveSize = size || 0;
+    this.__flatSize = size || 0;
   }
 
   /**
@@ -104,7 +107,7 @@ export class Cache {
    * @return {boolean}
    */
   get isLoading() {
-    if (this.pendingRequests.size > 0) {
+    if (Object.keys(this.pendingRequests).length > 0) {
       return true;
     }
 
@@ -116,20 +119,33 @@ export class Cache {
    *
    * @return {number}
    */
+  get flatSize() {
+    return this.__flatSize;
+  }
+
+  /**
+   * 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() {
-    return this.__effectiveSize;
+    console.warn(
+      '<vaadin-grid> The `effectiveSize` property of ItemCache is deprecated and will be removed in Vaadin 25.',
+    );
+    return this.flatSize;
   }
 
   /**
-   * Recalculates the effective size for the cache and its descendant caches recursively.
+   * Recalculates the flattened size for the cache and its descendant caches recursively.
    */
-  recalculateEffectiveSize() {
-    this.__effectiveSize =
+  recalculateFlatSize() {
+    this.__flatSize =
       !this.parentItem || this.context.isExpanded(this.parentItem)
         ? this.size +
           this.subCaches.reduce((total, subCache) => {
-            subCache.recalculateEffectiveSize();
-            return total + subCache.effectiveSize;
+            subCache.recalculateFlatSize();
+            return total + subCache.flatSize;
           }, 0)
         : 0;
   }
@@ -201,7 +217,69 @@ export class Cache {
 
     return this.subCaches.reduce((prev, subCache) => {
       const index = subCache.parentCacheIndex;
-      return clampedIndex > index ? prev + subCache.effectiveSize : prev;
+      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,172 @@
+/**
+ * @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';
+import type { getFlatIndexByPath, getFlatIndexContext, getItemContext } from './helpers.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 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.
+   */
+  rootCache: Cache<TItem>;
+
+  constructor(
+    host: HTMLElement,
+    config: {
+      size?: number;
+      pageSize: number;
+      getItemId(item: TItem): unknown;
+      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 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.
+   */
+  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[]): ReturnType<typeof getFlatIndexByPath<TItem>>;
+
+  /**
+   * 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;
+}

package/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,6 +50,14 @@ 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.
    *
@@ -57,27 +65,31 @@ export class DataProviderController extends EventTarget {
    */
   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;
-    this.rootCache = this.__createRootCache();
+    this.rootCache = this.__createRootCache(size);
   }
 
   /**
    * The total number of items, including items from expanded sub-caches.
    */
-  get effectiveSize() {
-    return this.rootCache.effectiveSize;
+  get flatSize() {
+    return this.rootCache.flatSize;
   }
 
   /** @private */
   get __cacheContext() {
-    return { isExpanded: this.isExpanded };
+    return {
+      isExpanded: this.isExpanded,
+      // The controller instance is needed to ensure deprecated cache methods work.
+      __controller: this,
+    };
   }
 
   /**
@@ -89,17 +101,6 @@ export class DataProviderController extends EventTarget {
     return this.rootCache.isLoading;
   }
 
-  /**
-   * Sets the size for the root cache and recalculates the effective size.
-   *
-   * @param {number} size
-   */
-  setSize(size) {
-    this.size = size;
-    this.rootCache.size = size;
-    this.recalculateEffectiveSize();
-  }
-
   /**
    * Sets the page size and clears the cache.
    *
@@ -121,31 +122,49 @@ export class DataProviderController extends EventTarget {
   }
 
   /**
-   * Recalculates the effective size.
+   * Recalculates the flattened size.
    */
-  recalculateEffectiveSize() {
-    this.rootCache.recalculateEffectiveSize();
+  recalculateFlatSize() {
+    this.rootCache.recalculateFlatSize();
   }
 
   /**
    * Clears the cache.
    */
   clearCache() {
-    this.rootCache = this.__createRootCache();
+    this.rootCache = this.__createRootCache(this.rootCache.size);
   }
 
   /**
    * 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.
@@ -197,23 +216,26 @@ export class DataProviderController extends EventTarget {
   }
 
   /** @private */
-  __createRootCache() {
-    return new Cache(this.__cacheContext, this.pageSize, this.size);
+  __createRootCache(size) {
+    return new Cache(this.__cacheContext, this.pageSize, size);
   }
 
   /** @private */
   __loadCachePage(cache, page) {
-    if (!this.dataProvider || cache.pendingRequests.has(page)) {
+    if (!this.dataProvider || cache.pendingRequests[page]) {
       return;
     }
 
-    const params = {
+    let params = {
       page,
       pageSize: this.pageSize,
       parentItem: cache.parentItem,
-      ...this.dataProviderParams(),
     };
 
+    if (this.dataProviderParams) {
+      params = { ...params, ...this.dataProviderParams() };
+    }
+
     const callback = (items, size) => {
       if (size !== undefined) {
         cache.size = size;
@@ -223,16 +245,16 @@ export class DataProviderController extends EventTarget {
 
       cache.setPage(page, items);
 
-      this.recalculateEffectiveSize();
+      this.recalculateFlatSize();
 
       this.dispatchEvent(new CustomEvent('page-received'));
 
-      cache.pendingRequests.delete(page);
+      delete cache.pendingRequests[page];
 
       this.dispatchEvent(new CustomEvent('page-loaded'));
     };
 
-    cache.pendingRequests.set(page, callback);
+    cache.pendingRequests[page] = callback;
 
     this.dispatchEvent(new CustomEvent('page-requested'));
 

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

@@ -0,0 +1,63 @@
+/**
+ * @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 { Cache } from './cache.js';
+
+/**
+ * Returns context for the given flattened index, including:
+ * - the corresponding cache
+ * - 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<TItem>(
+  cache: Cache<TItem>,
+  flatIndex: number,
+  level: number,
+): {
+  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<TItem>(cache: Cache<TItem>, path: number[], flatIndex: number): number;

package/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;
@@ -23,10 +26,10 @@ export function getFlatIndexContext(cache, flatIndex, level = 0) {
     const index = subCache.parentCacheIndex;
     if (levelIndex <= index) {
       break;
-    } else if (levelIndex <= index + subCache.effectiveSize) {
+    } else if (levelIndex <= index + subCache.flatSize) {
       return getFlatIndexContext(subCache, levelIndex - index - 1, level + 1);
     }
-    levelIndex -= subCache.effectiveSize;
+    levelIndex -= subCache.flatSize;
   }
 
   return {
@@ -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.
@@ -56,7 +105,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.js

@@ -3,9 +3,16 @@
  * 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-alpha11';
+      },
+    });
+
     customElements.define(CustomElement.is, CustomElement);
   } else {
     const definedVersion = defined.version;

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.3.0-alpha1';
-    }
-
     /** @protected */
     static finalize() {
       super.finalize();

package/src/url-utils.d.ts

@@ -5,6 +5,7 @@
  */
 
 /**
- * Check if two paths match
+ * Check if two paths can be resolved as URLs
+ * with the same origin and pathname.
  */
 export declare function matchPaths(path1: string, path2: string): boolean;

package/src/url-utils.js

@@ -5,12 +5,15 @@
  */
 
 /**
- * Check if two paths match
+ * Check if two paths can be resolved as URLs
+ * with the same origin and pathname.
  *
  * @param {string} path1
  * @param {string} path2
  */
 export function matchPaths(path1, path2) {
   const base = document.baseURI;
-  return new URL(path1, base).pathname === new URL(path2, base).pathname;
+  const url1 = new URL(path1, base);
+  const url2 = new URL(path2, base);
+  return url1.origin === url2.origin && url1.pathname === url2.pathname;
 }

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,9 +127,16 @@ 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() {
+    const startPhysicalCount = this._physicalCount;
     // The scroll target is hidden.
     if (this.scrollTarget.offsetHeight === 0) {
       return;
@@ -133,6 +154,11 @@ export class IronListAdapter {
     if (this.__debouncerWheelAnimationFrame) {
       this.__debouncerWheelAnimationFrame.flush();
     }
+
+    if (this._physicalCount !== startPhysicalCount) {
+      // Flushing again until physical count stabilizes fixes https://github.com/vaadin/flow-components/issues/5595#issuecomment-1770278913
+      this.flush();
+    }
   }
 
   update(startIndex = 0, endIndex = this.size - 1) {
@@ -199,8 +225,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 +251,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 +269,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) {
@@ -278,6 +310,7 @@ export class IronListAdapter {
       this.__preventElementUpdates = false;
     } else {
       // Already initialized, just update _virtualCount
+      this._updateScrollerSize();
       this._virtualCount = this.items.length;
     }