WEBDEV-7939 Upgrade infinite-scroller to new version with CSS-transform-based virtualization (#582)

* Install new infinite scroller

* Update scrollToPage and template for new scroller behavior

* Debounce page fetches while scrolling rapidly

* Fix demo app bug with jumping to pages

* Upgrade infinite scroller alpha version

* Correct page change events and improve page jump accuracy

* Upgrade infinite-scroller alpha version

* Cache whether items use waveform thumbnails, to mitigate flickering

* Upgrade infinite-scroller alpha version

* Upgrade scroller alpha version

* Upgrade off alpha version

Author: latonv

package.json

@@ -31,7 +31,7 @@
     "@internetarchive/histogram-date-range": "^1.4.2",
     "@internetarchive/ia-dropdown": "^2.0.0",
     "@internetarchive/iaux-item-metadata": "^1.0.5",
-    "@internetarchive/infinite-scroller": "^1.0.1",
+    "@internetarchive/infinite-scroller": "^2.0.0",
     "@internetarchive/modal-manager": "^2.0.5",
     "@internetarchive/search-service": "^2.7.1",
     "@internetarchive/shared-resize-observer": "^0.2.0",

src/app-root.ts

@@ -112,6 +112,9 @@ export class AppRoot extends LitElement {
     const page = this.currentPage ?? 1;
     if (page > 1) {
       this.collectionBrowser.goToPage(page);
+    } else {
+      // Ensure we reset the initial page
+      this.collectionBrowser.initialPageNumber = 1;
     }
   }
 

src/collection-browser.ts

@@ -421,19 +421,69 @@ export class CollectionBrowser
     const model = this.dataSource.getTileModelAt(index);
     /**
      * If we encounter a model we don't have yet and we're not in the middle of an
-     * automated scroll, fetch the page and just return undefined.
+     * automated scroll, schedule a fetch for the missing page and return undefined.
      * The datasource will be updated once the page is loaded and the cell will be rendered.
      *
      * We disable it during the automated scroll since we don't want to fetch pages for intervening cells the
      * user may never see.
      */
     if (!model && !this.isScrollingToCell && this.dataSource.queryInitialized) {
       const pageNumber = Math.floor(index / this.pageSize) + 1;
-      this.dataSource.fetchPage(pageNumber);
+      this.scheduleDeferredPageFetch(pageNumber);
     }
     return model;
   }
 
+  /**
+   * Debounce delay for page fetches initiated by new cells becoming visible.
+   * Tuned so quick scrolling through unloaded regions doesn't send rapid-fire
+   * search requests for every page we pass through, but to still feel responsive
+   * when the scroll ends.
+   */
+  private static readonly DEFERRED_FETCH_DELAY_MS = 150;
+
+  private deferredFetchTimer = 0;
+
+  /**
+   * Schedules a fetch for the given page, debounced to ensure we don't
+   * rapid-fire fetches while scrolling through pages quickly.
+   *
+   * If there's no pending fetch timer yet, it will fire a fetch immediately.
+   * Otherwise, it will reset any existing timer. In either case, a deferred
+   * fetch for the visible pages is scheduled after a brief delay to account
+   * for whatever pages we land on after scrolling.
+   */
+  private scheduleDeferredPageFetch(pageNumber: number): void {
+    if (!this.deferredFetchTimer) {
+      this.dataSource.fetchPage(pageNumber);
+    } else {
+      window.clearTimeout(this.deferredFetchTimer);
+    }
+
+    this.deferredFetchTimer = window.setTimeout(() => {
+      this.deferredFetchTimer = 0;
+      this.fetchVisiblePages();
+    }, CollectionBrowser.DEFERRED_FETCH_DELAY_MS);
+  }
+
+  /**
+   * Fetch each currently-visible page whose first cell still has no
+   * loaded model.
+   */
+  private fetchVisiblePages(): void {
+    const visibleIndices = this.infiniteScroller?.getVisibleCellIndices() ?? [];
+    const visiblePages = new Set(
+      visibleIndices.map(i => Math.floor(i / this.pageSize) + 1),
+    );
+
+    for (const page of visiblePages) {
+      const firstCellOfPage = (page - 1) * this.pageSize;
+      if (!this.dataSource.getTileModelAt(firstCellOfPage)) {
+        this.dataSource.fetchPage(page);
+      }
+    }
+  }
+
   // this is the total number of tiles we expect if
   // the data returned is a full page worth
   // this is useful for putting in placeholders for the expected number of tiles
@@ -866,6 +916,8 @@ export class CollectionBrowser
       class=${this.infiniteScrollerClasses}
       itemCount=${this.placeholderType ? 0 : nothing}
       ariaLandmarkLabel="Search results"
+      .estimatedCellHeight=${this.estimatedTileHeight}
+      .minBufferMarginCells=${this.pageSize}
       .cellProvider=${this}
       .placeholderCellTemplate=${this.placeholderCellTemplate}
       @scrollThresholdReached=${this.scrollThresholdReached}
@@ -887,6 +939,25 @@ export class CollectionBrowser
     });
   }
 
+  /**
+   * Best-effort hint of how tall a single rendered tile is, by display mode.
+   * The scroller uses this to better estimate the size its initial scroll
+   * spacer and buffer position before real cell heights are measured.
+   * Should roughly match the placeholder heights since the initial render
+   * of a new page generally shows placeholders only anyway.
+   */
+  private get estimatedTileHeight(): number {
+    switch (this.displayMode) {
+      case 'list-detail':
+        return 80;
+      case 'list-compact':
+        return 45;
+      case 'grid':
+      default:
+        return 225;
+    }
+  }
+
   /**
    * Template for the sort & filtering bar that appears atop the search results.
    */
@@ -1098,7 +1169,7 @@ export class CollectionBrowser
     if ((this.currentPage ?? 1) > 1) {
       this.goToPage(1);
     }
-    this.currentPage = 1;
+    this.setCurrentPage(1);
   }
 
   /**
@@ -1871,6 +1942,11 @@ export class CollectionBrowser
       window.removeEventListener('popstate', this.boundNavigationHandler);
     }
 
+    if (this.deferredFetchTimer) {
+      window.clearTimeout(this.deferredFetchTimer);
+      this.deferredFetchTimer = 0;
+    }
+
     this.leftColIntersectionObserver?.disconnect();
     this.facetsIntersectionObserver?.disconnect();
     window.removeEventListener('resize', this.updateLeftColumnHeight);
@@ -2123,27 +2199,45 @@ export class CollectionBrowser
   private visibleCellsChanged(
     e: CustomEvent<{ visibleCellIndices: number[] }>,
   ) {
+    this.updateVisiblePage(e.detail.visibleCellIndices);
+  }
+
+  /**
+   * Recomputes the current page from the given set of visible cell indices
+   * and emits `visiblePageChanged` if the page actually changed.
+   */
+  private updateVisiblePage(visibleCellIndices: number[]): void {
     if (this.isScrollingToCell) return;
-    const { visibleCellIndices } = e.detail;
     if (visibleCellIndices.length === 0) return;
 
+    // The indices aren't necessarily sorted, so sort them here to ensure our
+    // calculations below find the right cell/page.
+    const sorted = [...visibleCellIndices].sort((a, b) => a - b);
+
     // For page determination, do not count more than a single page of visible cells,
     // since otherwise patrons using very tall screens will be treated as one page
     // further than they actually are.
     const lastIndexWithinCurrentPage =
-      Math.min(this.pageSize, visibleCellIndices.length) - 1;
-    const lastVisibleCellIndex = visibleCellIndices[lastIndexWithinCurrentPage];
+      Math.min(this.pageSize, sorted.length) - 1;
+    const lastVisibleCellIndex = sorted[lastIndexWithinCurrentPage];
     const lastVisibleCellPage =
       Math.floor(lastVisibleCellIndex / this.pageSize) + 1;
-    if (this.currentPage !== lastVisibleCellPage) {
-      this.currentPage = lastVisibleCellPage;
-    }
-    const event = new CustomEvent('visiblePageChanged', {
-      detail: {
-        pageNumber: lastVisibleCellPage,
-      },
-    });
-    this.dispatchEvent(event);
+
+    this.setCurrentPage(lastVisibleCellPage);
+  }
+
+  /**
+   * Sets the current page number and emits a `visiblePageChanged`
+   * event if the new page differs from the previous one.
+   */
+  private setCurrentPage(pageNumber: number): void {
+    if (this.currentPage === pageNumber) return;
+    this.currentPage = pageNumber;
+    this.dispatchEvent(
+      new CustomEvent('visiblePageChanged', {
+        detail: { pageNumber },
+      }),
+    );
   }
 
   // we only want to scroll on the very first query change
@@ -2243,10 +2337,10 @@ export class CollectionBrowser
     this.selectedCreatorFilter = restorationState.selectedCreatorFilter ?? null;
     this.selectedFacets = restorationState.selectedFacets;
     if (!this.suppressURLQuery) this.baseQuery = restorationState.baseQuery;
-    this.currentPage = restorationState.currentPage ?? 1;
+    this.setCurrentPage(restorationState.currentPage ?? 1);
     this.minSelectedDate = restorationState.minSelectedDate;
     this.maxSelectedDate = restorationState.maxSelectedDate;
-    if (this.currentPage > 1) {
+    if (this.currentPage && this.currentPage > 1) {
       this.goToPage(this.currentPage);
     }
   }
@@ -2323,25 +2417,43 @@ export class CollectionBrowser
     });
   }
 
-  private scrollToPage(pageNumber: number): Promise<void> {
-    return new Promise(resolve => {
-      const cellIndexToScrollTo = this.pageSize * (pageNumber - 1);
-      // without this setTimeout, Safari just pauses until the `fetchPage` is complete
-      // then scrolls to the cell
-      setTimeout(() => {
-        this.isScrollingToCell = true;
-        this.infiniteScroller?.scrollToCell(cellIndexToScrollTo, true);
-        // This timeout is to give the scroll animation time to finish
-        // then updating the infinite scroller once we're done scrolling
-        // There's no scroll animation completion callback so we're
-        // giving it 0.5s to finish.
-        setTimeout(() => {
-          this.isScrollingToCell = false;
-          this.infiniteScroller?.refreshAllVisibleCells();
-          resolve();
-        }, 500);
-      }, 0);
+  private async scrollToPage(pageNumber: number): Promise<void> {
+    const cellIndexToScrollTo = this.pageSize * (pageNumber - 1);
+
+    // Wait for the infinite scroller be rendered before proceeding
+    let waitAttempts = 0;
+    while (!this.infiniteScroller && waitAttempts < 20) {
+      await this.updateComplete;
+      waitAttempts++;
+    }
+    if (!this.infiniteScroller) return;
+
+    // The scroller have its default `itemCount=0`, so propagate our estimated
+    // tile count before jumping to the desired page.
+    if (this.infiniteScroller.itemCount < this.estimatedTileCount) {
+      this.infiniteScroller.itemCount = this.estimatedTileCount;
+      await this.updateComplete;
+    }
+
+    // Without this setTimeout(0), Safari just pauses until the `fetchPage`
+    // is complete then scrolls to the cell.
+    await new Promise<void>(resolve => {
+      setTimeout(resolve, 0);
     });
+
+    this.isScrollingToCell = true;
+    const scrolled = await this.infiniteScroller.scrollToCell(
+      cellIndexToScrollTo,
+      true,
+    );
+    this.isScrollingToCell = false;
+    this.infiniteScroller.refreshAllVisibleCells();
+
+    // After we finish scrolling, recompute the visible page from the new state
+    // so that it doesn't fall out of sync.
+    if (scrolled) {
+      this.updateVisiblePage(this.infiniteScroller.getVisibleCellIndices());
+    }
   }
 
   /**

src/tiles/item-image.ts

@@ -1,4 +1,11 @@
-import { css, CSSResultGroup, html, LitElement, nothing } from 'lit';
+import {
+  css,
+  CSSResultGroup,
+  html,
+  LitElement,
+  nothing,
+  PropertyValues,
+} from 'lit';
 import { customElement, property, query, state } from 'lit/decorators.js';
 import { ClassInfo, classMap } from 'lit/directives/class-map.js';
 
@@ -12,6 +19,14 @@ import { searchIcon } from '../assets/img/icons/mediatype/search';
 
 @customElement('item-image')
 export class ItemImage extends LitElement {
+  /**
+   * Map to cache which identifiers have waveform-style thumbnails, so that
+   * they can have their waveform styling applied immediately, rather than
+   * waiting for the image content to load before applying it (which can
+   * cause noticeable flicker when such tiles refresh).
+   */
+  private static readonly waveformByIdentifier = new Map<string, boolean>();
+
   @property({ type: Object }) model?: TileModel;
 
   @property({ type: String }) baseImageUrl?: string;
@@ -30,6 +45,15 @@ export class ItemImage extends LitElement {
 
   @query('img') private baseImage!: HTMLImageElement;
 
+  protected willUpdate(changed: PropertyValues): void {
+    if (changed.has('model')) {
+      // If this identifier is known to have a waveform image, then set isWaveform upfront
+      const identifier = this.model?.identifier;
+      this.isWaveform =
+        ItemImage.waveformByIdentifier.get(identifier as string) === true;
+    }
+  }
+
   render() {
     return html`
       <div class=${classMap(this.itemBaseClass)}>${this.imageTemplate}</div>
@@ -149,6 +173,9 @@ export class ItemImage extends LitElement {
       this.baseImage.naturalWidth / this.baseImage.naturalHeight === 4
     ) {
       this.isWaveform = true;
+      if (this.model?.identifier) {
+        ItemImage.waveformByIdentifier.set(this.model.identifier, true);
+      }
     }
   }
 

yarn.lock

@@ -269,12 +269,12 @@
   dependencies:
     lit-html "^1.2.1"
 
-"@internetarchive/infinite-scroller@^1.0.1":
-  version "1.0.1"
-  resolved "https://registry.npmjs.org/@internetarchive/infinite-scroller/-/infinite-scroller-1.0.1.tgz"
-  integrity sha512-wzl7bQLidNZ4uXgP0H8AA3HoAXxueoHaVcpgQMXR7bspHKGvgLy8EvLbprBps1dFNK5yZRH9PHdLRtJgpcWKtQ==
+"@internetarchive/infinite-scroller@^2.0.0":
+  version "2.0.0"
+  resolved "https://registry.yarnpkg.com/@internetarchive/infinite-scroller/-/infinite-scroller-2.0.0.tgz#b7fbc9ad94c12225653b3718174d0712838638be"
+  integrity sha512-PGfi0eqdSfsVd3xS2W9abY+iAJQPcw/Z8x9kWYARhiwot35eAMWxFzCXm5FaRTTjEQjZFEOBdXrQFNlO8GBNsQ==
   dependencies:
-    lit "^2.0.2"
+    lit "^2.8.0 || ^3.3.2"
 
 "@internetarchive/lazy-loader-service@^0.2.0":
   version "0.2.0"
@@ -4056,7 +4056,7 @@ lit-html@^3.3.0:
     lit-element "^4.2.0"
     lit-html "^3.3.0"
 
-lit@^2.0.2, lit@^2.2.7, lit@^2.3.0, lit@^2.8.0:
+lit@^2.2.7, lit@^2.3.0, lit@^2.8.0:
   version "2.8.0"
   resolved "https://registry.npmjs.org/lit/-/lit-2.8.0.tgz"
   integrity sha512-4Sc3OFX9QHOJaHbmTMk28SYgVxLN3ePDjg7hofEft2zWlehFL3LiAuapWc4U/kYwMYJSh2hTCPZ6/LIC7ii0MA==