@internetarchive/collection-browser 0.4.16-alpha.9 → 0.4.17

package/src/collection-browser.ts

@@ -55,7 +55,7 @@ import {
   PrefixFilterType,
   PrefixFilterCounts,
   prefixFilterAggregationKeys,
-  FacetOption,
+  FacetEventDetails,
 } from './models';
 import {
   RestorationStateHandlerInterface,
@@ -104,10 +104,6 @@ export class CollectionBrowser
 
   @property({ type: Object }) resizeObserver?: SharedResizeObserverInterface;
 
-  @property({ type: String }) titleQuery?: string;
-
-  @property({ type: String }) creatorQuery?: string;
-
   @property({ type: Number }) currentPage?: number;
 
   @property({ type: String }) minSelectedDate?: string;
@@ -189,6 +185,8 @@ export class CollectionBrowser
 
   @query('#content-container') private contentContainer!: HTMLDivElement;
 
+  @query('#left-column') private leftColumn?: HTMLDivElement;
+
   @property({ type: Object, attribute: false })
   private analyticsHandler?: AnalyticsManagerInterface;
 
@@ -209,6 +207,10 @@ export class CollectionBrowser
    */
   private isResizeToMobile = false;
 
+  private leftColIntersectionObserver?: IntersectionObserver;
+
+  private facetsIntersectionObserver?: IntersectionObserver;
+
   private placeholderCellTemplate = html`<collection-browser-loading-tile></collection-browser-loading-tile>`;
 
   private tileModelAtCellIndex(index: number): TileModel | undefined {
@@ -294,8 +296,6 @@ export class CollectionBrowser
     if (letterFilters) {
       this.selectedTitleFilter = null;
       this.selectedCreatorFilter = null;
-      this.titleQuery = undefined;
-      this.creatorQuery = undefined;
     }
 
     if (sort) {
@@ -339,11 +339,9 @@ export class CollectionBrowser
     this.placeholderType = null;
     if (!this.baseQuery?.trim()) {
       this.placeholderType = 'empty-query';
-    }
-
-    if (
-      (!this.searchResultsLoading && this.totalResults === 0) ||
-      !this.searchService
+    } else if (
+      !this.searchResultsLoading &&
+      (this.totalResults === 0 || !this.searchService)
     ) {
       this.placeholderType = 'null-result';
     }
@@ -370,7 +368,8 @@ export class CollectionBrowser
       this.searchResultsLoading || this.totalResults === undefined;
     const resultsCount = this.totalResults?.toLocaleString();
     const resultsLabel = this.totalResults === 1 ? 'Result' : 'Results';
-    return html`<div
+    return html` <div id="left-column-scroll-sentinel"></div>
+      <div
         id="left-column"
         class="column${this.isResizeToMobile ? ' preload' : ''}"
       >
@@ -392,7 +391,9 @@ export class CollectionBrowser
             : ''}
         >
           ${this.facetsTemplate}
+          <div id="facets-scroll-sentinel"></div>
         </div>
+        ${this.mobileView ? nothing : html`<div id="facets-bottom-fade"></div>`}
       </div>
       <div id="right-column" class="column">
         ${this.sortFilterBarTemplate}
@@ -497,9 +498,30 @@ export class CollectionBrowser
     }
   }
 
-  /** Send Analytics when sorting by title's first letter
+  /**
+   * Returns a query clause identifying the currently selected title filter,
+   * e.g., `firstTitle:X`.
+   */
+  private get titleQuery(): string | undefined {
+    return this.selectedTitleFilter
+      ? `firstTitle:${this.selectedTitleFilter}`
+      : undefined;
+  }
+
+  /**
+   * Returns a query clause identifying the currently selected creator filter,
+   * e.g., `firstCreator:X`.
+   */
+  private get creatorQuery(): string | undefined {
+    return this.selectedCreatorFilter
+      ? `firstCreator:${this.selectedCreatorFilter}`
+      : undefined;
+  }
+
+  /**
+   * Send Analytics when sorting by title's first letter
    * labels: 'start-<ToLetter>' | 'clear-<FromLetter>' | '<FromLetter>-<ToLetter>'
-   * */
+   */
   private sendFilterByTitleAnalytics(prevSelectedLetter: string | null): void {
     if (!prevSelectedLetter && !this.selectedTitleFilter) {
       return;
@@ -515,15 +537,10 @@ export class CollectionBrowser
     });
   }
 
-  private selectedTitleLetterChanged(): void {
-    this.titleQuery = this.selectedTitleFilter
-      ? `firstTitle:${this.selectedTitleFilter}`
-      : undefined;
-  }
-
-  /** Send Analytics when filtering by creator's first letter
+  /**
+   * Send Analytics when filtering by creator's first letter
    * labels: 'start-<ToLetter>' | 'clear-<FromLetter>' | '<FromLetter>-<ToLetter>'
-   * */
+   */
   private sendFilterByCreatorAnalytics(
     prevSelectedLetter: string | null
   ): void {
@@ -541,26 +558,24 @@ export class CollectionBrowser
     });
   }
 
-  private selectedCreatorLetterChanged(): void {
-    this.creatorQuery = this.selectedCreatorFilter
-      ? `firstCreator:${this.selectedCreatorFilter}`
-      : undefined;
-  }
-
+  /**
+   * Handler for changes to which letter is selected in the title alphabet bar.
+   */
   private titleLetterSelected(
     e: CustomEvent<{ selectedLetter: string | null }>
   ): void {
     this.selectedCreatorFilter = null;
     this.selectedTitleFilter = e.detail.selectedLetter;
-    this.selectedTitleLetterChanged();
   }
 
+  /**
+   * Handler for changes to which letter is selected in the creator alphabet bar.
+   */
   private creatorLetterSelected(
     e: CustomEvent<{ selectedLetter: string | null }>
   ): void {
     this.selectedTitleFilter = null;
     this.selectedCreatorFilter = e.detail.selectedLetter;
-    this.selectedCreatorLetterChanged();
   }
 
   private get mobileFacetsTemplate() {
@@ -603,13 +618,13 @@ export class CollectionBrowser
         .selectedFacets=${this.selectedFacets}
         .collectionNameCache=${this.collectionNameCache}
         .showHistogramDatePicker=${this.showHistogramDatePicker}
-        .query=${this.filteredQuery}
+        .query=${this.baseQuery}
         .filterMap=${this.filterMap}
         .modalManager=${this.modalManager}
         ?collapsableFacets=${this.mobileView}
         ?facetsLoading=${this.facetsLoading}
         ?fullYearAggregationLoading=${this.facetsLoading}
-        .onFacetClick=${this.facetClickHandler}
+        @facetClick=${this.facetClickHandler}
         .analyticsHandler=${this.analyticsHandler}
       >
       </collection-facets>
@@ -669,6 +684,16 @@ export class CollectionBrowser
   }
 
   updated(changed: PropertyValues) {
+    if (changed.has('placeholderType') && this.placeholderType === null) {
+      if (!this.leftColIntersectionObserver) {
+        this.setupLeftColumnScrollListeners();
+      }
+      if (!this.facetsIntersectionObserver) {
+        this.setupFacetsScrollListeners();
+      }
+      this.updateLeftColumnHeight();
+    }
+
     if (
       changed.has('displayMode') ||
       changed.has('baseNavigationUrl') ||
@@ -729,13 +754,11 @@ export class CollectionBrowser
       this.sendFilterByTitleAnalytics(
         changed.get('selectedTitleFilter') as string
       );
-      this.selectedTitleLetterChanged();
     }
     if (changed.has('selectedCreatorFilter')) {
       this.sendFilterByCreatorAnalytics(
         changed.get('selectedCreatorFilter') as string
       );
-      this.selectedCreatorLetterChanged();
     }
 
     if (
@@ -774,6 +797,10 @@ export class CollectionBrowser
     if (this.boundNavigationHandler) {
       window.removeEventListener('popstate', this.boundNavigationHandler);
     }
+
+    this.leftColIntersectionObserver?.disconnect();
+    this.facetsIntersectionObserver?.disconnect();
+    window.removeEventListener('resize', this.updateLeftColumnHeight);
   }
 
   handleResize(entry: ResizeObserverEntry): void {
@@ -785,8 +812,80 @@ export class CollectionBrowser
         this.isResizeToMobile = true;
       }
     }
+
+    // Ensure the facet sidebar remains sized correctly
+    this.updateLeftColumnHeight();
+  }
+
+  /**
+   * Sets up listeners for events that may require updating the left column height.
+   */
+  private setupLeftColumnScrollListeners(): void {
+    // We observe intersections between the left column's scroll sentinel and
+    // the viewport, so that we can ensure the left column is always sized to
+    // match the _available_ viewport height. This should generally be more
+    // performant than listening to scroll events on the page or column.
+    const leftColumnSentinel = this.shadowRoot?.querySelector(
+      '#left-column-scroll-sentinel'
+    );
+    if (leftColumnSentinel) {
+      this.leftColIntersectionObserver = new IntersectionObserver(
+        this.updateLeftColumnHeight,
+        {
+          threshold: [...Array(101).keys()].map(n => n / 100), // Threshold every 1%
+        }
+      );
+      this.leftColIntersectionObserver.observe(leftColumnSentinel);
+    }
+
+    // We also listen for window resize events, as they are not always captured
+    // by the resize observer and can affect the desired height of the left column.
+    window.addEventListener('resize', this.updateLeftColumnHeight);
+  }
+
+  /**
+   * Sets up listeners to control whether the facet sidebar shows its bottom fade-out.
+   * Note this uses a separate IntersectionObserver from the left column, because we
+   * don't need granular intersection thresholds for this.
+   */
+  private setupFacetsScrollListeners(): void {
+    const facetsSentinel = this.shadowRoot?.querySelector(
+      '#facets-scroll-sentinel'
+    );
+    if (facetsSentinel) {
+      this.facetsIntersectionObserver = new IntersectionObserver(
+        this.updateFacetFadeOut
+      );
+      this.facetsIntersectionObserver.observe(facetsSentinel);
+    }
   }
 
+  /**
+   * Updates the height of the left column according to its position on the page.
+   * Arrow function ensures proper `this` binding.
+   */
+  private updateLeftColumnHeight = (): void => {
+    if (this.mobileView) {
+      this.leftColumn?.style?.removeProperty('height');
+    } else {
+      const clientTop = this.leftColumn?.getBoundingClientRect().top;
+      this.leftColumn?.style?.setProperty(
+        'height',
+        `${window.innerHeight - (clientTop ?? 0) - 3}px`
+      );
+    }
+  };
+
+  /**
+   * Toggles whether the fade-out is visible at the bottom of the facets.
+   * It should only be visible if the facets are not scrolled to the bottom.
+   * Arrow function ensures proper `this` binding.
+   */
+  private updateFacetFadeOut = (entries: IntersectionObserverEntry[]): void => {
+    const fadeElmt = this.shadowRoot?.getElementById('facets-bottom-fade');
+    fadeElmt?.classList.toggle('hidden', entries?.[0]?.isIntersecting);
+  };
+
   private emitBaseQueryChanged() {
     this.dispatchEvent(
       new CustomEvent<{ baseQuery?: string }>('baseQueryChanged', {
@@ -952,6 +1051,11 @@ export class CollectionBrowser
     this.searchResultsLoading = false;
   }
 
+  /**
+   * Constructs a search service FilterMap object from the combination of
+   * all the currently-applied filters. This includes any facets, letter
+   * filters, and date range.
+   */
   private get filterMap(): FilterMap {
     const builder = new FilterMapBuilder();
 
@@ -995,21 +1099,24 @@ export class CollectionBrowser
       }
     }
 
-    const filterMap = builder.build();
-    return filterMap;
-  }
-
-  /** The base query joined with any title/creator letter filters */
-  private get filteredQuery(): string | undefined {
-    if (!this.baseQuery) return undefined;
-    let filteredQuery = this.baseQuery.trim();
-
-    const { sortFilterQueries } = this;
-    if (sortFilterQueries) {
-      filteredQuery += ` AND ${sortFilterQueries}`;
+    // Add any letter filters
+    if (this.selectedTitleFilter) {
+      builder.addFilter(
+        'firstTitle',
+        this.selectedTitleFilter,
+        FilterConstraint.INCLUDE
+      );
+    }
+    if (this.selectedCreatorFilter) {
+      builder.addFilter(
+        'firstCreator',
+        this.selectedCreatorFilter,
+        FilterConstraint.INCLUDE
+      );
     }
 
-    return filteredQuery.trim();
+    const filterMap = builder.build();
+    return filterMap;
   }
 
   /** The full query, including year facets and date range clauses */
@@ -1031,22 +1138,6 @@ export class CollectionBrowser
     return fullQuery.trim();
   }
 
-  /** The full query without any title/creator letter filters */
-  private get fullQueryWithoutAlphaFilters(): string | undefined {
-    if (!this.baseQuery) return undefined;
-    let fullQuery = this.baseQuery.trim();
-
-    const { facetQuery, dateRangeQueryClause } = this;
-
-    if (facetQuery) {
-      fullQuery += ` AND ${facetQuery}`;
-    }
-    if (dateRangeQueryClause) {
-      fullQuery += ` AND ${dateRangeQueryClause}`;
-    }
-    return fullQuery.trim();
-  }
-
   /**
    * Generates a query string for the given facets
    *
@@ -1137,36 +1228,39 @@ export class CollectionBrowser
     this.selectedFacets = e.detail;
   }
 
-  facetClickHandler(
-    name: FacetOption,
-    facetSelected: boolean,
-    negative: boolean
-  ): void {
+  facetClickHandler({
+    detail: { key, state: facetState, negative },
+  }: CustomEvent<FacetEventDetails>): void {
     if (negative) {
       this.analyticsHandler?.sendEvent({
         category: this.searchContext,
-        action: facetSelected
-          ? analyticsActions.facetNegativeSelected
-          : analyticsActions.facetNegativeDeselected,
-        label: name,
+        action:
+          facetState !== 'none'
+            ? analyticsActions.facetNegativeSelected
+            : analyticsActions.facetNegativeDeselected,
+        label: key,
       });
     } else {
       this.analyticsHandler?.sendEvent({
         category: this.searchContext,
-        action: facetSelected
-          ? analyticsActions.facetSelected
-          : analyticsActions.facetDeselected,
-        label: name,
+        action:
+          facetState !== 'none'
+            ? analyticsActions.facetSelected
+            : analyticsActions.facetDeselected,
+        label: key,
       });
     }
   }
 
   private async fetchFacets() {
-    if (!this.filteredQuery) return;
+    const trimmedQuery = this.baseQuery?.trim();
+    if (!trimmedQuery) return;
     if (!this.searchService) return;
 
+    const { facetFetchQueryKey } = this;
+
     const params: SearchParams = {
-      query: this.filteredQuery,
+      query: trimmedQuery,
       rows: 0,
       filters: this.filterMap,
       // Fetch a few extra buckets beyond the 6 we show, in case some get suppressed
@@ -1182,7 +1276,13 @@ export class CollectionBrowser
       this.searchType
     );
     const success = searchResponse?.success;
-    this.facetsLoading = false;
+
+    // This is checking to see if the query has changed since the data was fetched.
+    // If so, we just want to discard this set of aggregations because they are
+    // likely no longer valid for the newer query.
+    const queryChangedSinceFetch =
+      facetFetchQueryKey !== this.facetFetchQueryKey;
+    if (queryChangedSinceFetch) return;
 
     if (!success) {
       const errorMsg = searchResponse?.error?.message;
@@ -1199,17 +1299,23 @@ export class CollectionBrowser
       return;
     }
 
-    // This is checking to see if the query has changed since the data was fetched.
-    // If so, we just want to discard this set of aggregations because they are
-    // likely no longer valid for the newer query.
-    const returnedUid = (success.request.clientParameters as any).uid;
-    const queryChangedSinceFetch = returnedUid !== this.facetFetchQueryKey;
-    if (queryChangedSinceFetch) return;
+    const { aggregations, collectionTitles } = success.response;
+    this.aggregations = aggregations;
 
-    this.aggregations = success?.response.aggregations;
+    if (collectionTitles) {
+      this.collectionNameCache?.addKnownTitles(collectionTitles);
+    } else if (this.aggregations?.collection) {
+      this.collectionNameCache?.preloadIdentifiers(
+        (this.aggregations.collection.buckets as Bucket[]).map(bucket =>
+          bucket.key?.toString()
+        )
+      );
+    }
 
     this.fullYearsHistogramAggregation =
       success?.response?.aggregations?.year_histogram;
+
+    this.facetsLoading = false;
   }
 
   private scrollToPage(pageNumber: number): Promise<void> {
@@ -1264,7 +1370,8 @@ export class CollectionBrowser
   private pageFetchesInProgress: Record<string, Set<number>> = {};
 
   async fetchPage(pageNumber: number) {
-    if (!this.filteredQuery) return;
+    const trimmedQuery = this.baseQuery?.trim();
+    if (!trimmedQuery) return;
     if (!this.searchService) return;
 
     // if we already have data, don't fetch again
@@ -1282,7 +1389,7 @@ export class CollectionBrowser
 
     const sortParams = this.sortParam ? [this.sortParam] : [];
     const params: SearchParams = {
-      query: this.filteredQuery,
+      query: trimmedQuery,
       page: pageNumber,
       rows: this.pageSize,
       sort: sortParams,
@@ -1296,6 +1403,12 @@ export class CollectionBrowser
     );
     const success = searchResponse?.success;
 
+    // This is checking to see if the query has changed since the data was fetched.
+    // If so, we just want to discard the data since there should be a new query
+    // right behind it.
+    const queryChangedSinceFetch = pageFetchQueryKey !== this.pageFetchQueryKey;
+    if (queryChangedSinceFetch) return;
+
     if (!success) {
       const errorMsg = searchResponse?.error?.message;
       const detailMsg = searchResponse?.error?.details?.message;
@@ -1310,21 +1423,20 @@ export class CollectionBrowser
         window?.Sentry?.captureMessage?.(this.queryErrorMessage, 'error');
       }
 
+      this.pageFetchesInProgress[pageFetchQueryKey]?.delete(pageNumber);
+      this.searchResultsLoading = false;
       return;
     }
 
-    // This is checking to see if the query has changed since the data was fetched.
-    // If so, we just want to discard the data since there should be a new query
-    // right behind it.
-    const returnedUid = (success.request.clientParameters as any).uid;
-    const queryChangedSinceFetch = returnedUid !== this.pageFetchQueryKey;
-    if (queryChangedSinceFetch) return;
-
     this.totalResults = success.response.totalResults;
 
-    const { results } = success.response;
+    const { results, collectionTitles } = success.response;
     if (results && results.length > 0) {
-      this.preloadCollectionNames(results);
+      if (collectionTitles) {
+        this.collectionNameCache?.addKnownTitles(collectionTitles);
+      } else {
+        this.preloadCollectionNames(results);
+      }
       this.updateDataSource(pageNumber, results);
     }
 
@@ -1337,6 +1449,7 @@ export class CollectionBrowser
         this.infiniteScroller.itemCount = this.totalResults;
       }
     }
+
     this.pageFetchesInProgress[pageFetchQueryKey]?.delete(pageNumber);
     this.searchResultsLoading = false;
   }
@@ -1442,12 +1555,14 @@ export class CollectionBrowser
   private async fetchPrefixFilterBuckets(
     filterType: PrefixFilterType
   ): Promise<Bucket[]> {
-    if (!this.fullQueryWithoutAlphaFilters) return [];
+    const trimmedQuery = this.baseQuery?.trim();
+    if (!trimmedQuery) return [];
 
     const filterAggregationKey = prefixFilterAggregationKeys[filterType];
     const params: SearchParams = {
-      query: this.fullQueryWithoutAlphaFilters,
+      query: trimmedQuery,
       rows: 0,
+      filters: this.filterMap,
       // Only fetch the firstTitle or firstCreator aggregation
       aggregations: { simpleParams: [filterAggregationKey] },
       // Fetch all 26 letter buckets
@@ -1468,7 +1583,15 @@ export class CollectionBrowser
   private async updatePrefixFilterCounts(
     filterType: PrefixFilterType
   ): Promise<void> {
+    const { facetFetchQueryKey } = this;
     const buckets = await this.fetchPrefixFilterBuckets(filterType);
+
+    // Don't update the filter counts for an outdated query (if it has been changed
+    // since we sent the request)
+    const queryChangedSinceFetch =
+      facetFetchQueryKey !== this.facetFetchQueryKey;
+    if (queryChangedSinceFetch) return;
+
     // Unpack the aggregation buckets into a simple map like { 'A': 50, 'B': 25, ... }
     this.prefixFilterCountMap = { ...this.prefixFilterCountMap }; // Clone the object to trigger an update
     this.prefixFilterCountMap[filterType] = buckets.reduce(
@@ -1560,6 +1683,9 @@ export class CollectionBrowser
   static styles = css`
     :host {
       display: block;
+
+      --leftColumnWidth: 18rem;
+      --leftColumnPaddingRight: 2.5rem;
     }
 
     /**
@@ -1620,15 +1746,91 @@ export class CollectionBrowser
     }
 
     #left-column {
-      width: 18rem;
-      min-width: 18rem; /* Prevents Safari from shrinking col at first draw */
-      padding-right: 12px;
-      padding-right: 2.5rem;
+      width: var(--leftColumnWidth, 18rem);
+      /* Prevents Safari from shrinking col at first draw */
+      min-width: var(--leftColumnWidth, 18rem);
+      padding-top: 0;
+      /* Reduced padding by 0.2rem to add the invisible border in the rule below */
+      padding-right: calc(var(--leftColumnPaddingRight, 2.5rem) - 0.2rem);
+      border-right: 0.2rem solid transparent; /* Pads to the right of the scrollbar a bit */
       z-index: 1;
     }
 
+    .desktop #left-column {
+      top: 0;
+      position: sticky;
+      height: calc(100vh - 2rem);
+      max-height: calc(100vh - 2rem);
+      overflow-x: hidden;
+      overflow-y: scroll;
+
+      /*
+       * Firefox doesn't support any of the -webkit-scrollbar stuff below, but
+       * does at least give us a tiny bit of control over width & color.
+       */
+      scrollbar-width: thin;
+      scrollbar-color: transparent transparent;
+    }
+    .desktop #left-column:hover {
+      scrollbar-color: auto;
+    }
     .desktop #left-column::-webkit-scrollbar {
-      display: none;
+      appearance: none;
+      width: 6px;
+    }
+    .desktop #left-column::-webkit-scrollbar-button {
+      height: 3px;
+      background: transparent;
+    }
+    .desktop #left-column::-webkit-scrollbar-corner {
+      background: transparent;
+    }
+    .desktop #left-column::-webkit-scrollbar-thumb {
+      border-radius: 4px;
+    }
+    .desktop #left-column:hover::-webkit-scrollbar-thumb {
+      background: rgba(0, 0, 0, 0.15);
+    }
+    .desktop #left-column:hover::-webkit-scrollbar-thumb:hover {
+      background: rgba(0, 0, 0, 0.2);
+    }
+    .desktop #left-column:hover::-webkit-scrollbar-thumb:active {
+      background: rgba(0, 0, 0, 0.3);
+    }
+
+    #facets-bottom-fade {
+      background: linear-gradient(
+        to bottom,
+        #f5f5f700 0%,
+        #f5f5f7c0 50%,
+        #f5f5f7 80%,
+        #f5f5f7 100%
+      );
+      position: fixed;
+      bottom: 0;
+      height: 50px;
+      /* Wide enough to cover the content, but leave the scrollbar uncovered */
+      width: calc(
+        var(--leftColumnWidth) + var(--leftColumnPaddingRight) - 10px
+      );
+      z-index: 2;
+      pointer-events: none;
+      transition: height 0.1s ease;
+    }
+    #facets-bottom-fade.hidden {
+      height: 0;
+    }
+
+    .desktop #left-column-scroll-sentinel {
+      width: 1px;
+      height: 100vh;
+      background: transparent;
+    }
+
+    .desktop #facets-scroll-sentinel {
+      width: 1px;
+      height: 1px;
+      background: transparent;
     }
 
     .mobile #left-column {
@@ -1636,21 +1838,16 @@ export class CollectionBrowser
       padding: 0;
     }
 
-    .desktop #left-column {
-      top: 0;
-      position: sticky;
-      max-height: 100vh;
-      overflow: scroll;
-      -ms-overflow-style: none; /* hide scrollbar IE and Edge */
-      scrollbar-width: none; /* hide scrollbar Firefox */
-    }
-
     #mobile-header-container {
       display: flex;
       justify-content: space-between;
       align-items: center;
     }
 
+    .desktop #mobile-header-container {
+      padding-top: 2rem;
+    }
+
     #facets-container {
       position: relative;
       max-height: 0;