@internetarchive/collection-browser 2.2.2 → 2.2.3-alpha.0

package/dist/src/collection-browser.d.ts

@@ -7,7 +7,7 @@ import '@internetarchive/infinite-scroller';
 import type { ModalManagerInterface } from '@internetarchive/modal-manager';
 import type { FeatureFeedbackServiceInterface } from '@internetarchive/feature-feedback';
 import type { RecaptchaManagerInterface } from '@internetarchive/recaptcha-manager';
-import { SelectedFacets, SortField, CollectionBrowserContext, TileModel, CollectionDisplayMode, FacetEventDetails } from './models';
+import { SelectedFacets, SortField, CollectionBrowserContext, TileModel, CollectionDisplayMode, FacetEventDetails, FacetLoadStrategy } from './models';
 import { RestorationStateHandlerInterface } from './restoration-state-handler';
 import type { CollectionBrowserQueryState, CollectionBrowserSearchInterface } from './data-source/collection-browser-query-state';
 import type { CollectionBrowserDataSourceInterface } from './data-source/collection-browser-data-source-interface';
@@ -80,12 +80,6 @@ export declare class CollectionBrowser extends LitElement implements InfiniteScr
      * If true, the `query` param will not be added to the URL or updated on query changes.
      */
     suppressURLQuery: boolean;
-    /**
-     * Whether to suppress the display of facets entirely.
-     * If true, the facet sidebar content will be replaced by a message that facets are
-     * temporarily unavailable.
-     */
-    suppressFacets: boolean;
     /**
      * Whether to suppress display of the sort bar.
      * If true, the entire sort bar (incl. display modes) will be omitted from rendering.
@@ -97,12 +91,21 @@ export declare class CollectionBrowser extends LitElement implements InfiniteScr
      */
     suppressDisplayModes: boolean;
     /**
-     * Whether facets should be lazy-loaded.
-     * If false (default), facet data will be loaded eagerly along with search hits.
-     * If true, facet data will only be requested once the facet pane actually becomes visible,
-     * either by displaying in desktop mode or by the mobile facet dropdown being opened.
+     * What strategy to use for when/whether to load facet data for a search.
+     *
+     * Defaults to `eager`, always loading facets immediately alongside search results.
+     *
+     * To eliminate facets that are never seen, this can be reduced to `lazy-mobile`, which
+     * will delay loading facets in the mobile view until the "Filters" accordion is opened.
+     * Facets are still loaded eagerly when viewing the desktop layout.
+     *
+     * To further reduce facet requests for patrons who do not need to use them, this can be
+     * again reduced to `opt-in`, which will also require desktop users to explicitly request
+     * that they be loaded (in addition to the lazy mobile behavior described above).
+     *
+     * To entirely suppress facets from being loaded, this may be set to `off`.
      */
-    lazyLoadFacets: boolean;
+    facetLoadStrategy: FacetLoadStrategy;
     clearResultsOnEmptyQuery: boolean;
     collectionPagePath: string;
     /** describes where this component is being used */
@@ -146,6 +149,7 @@ export declare class CollectionBrowser extends LitElement implements InfiniteScr
      */
     private searchResultsLoading;
     private facetsLoading;
+    private facetsOptedIn;
     private totalResults?;
     private mobileView;
     private mobileFacetsVisible;
@@ -355,6 +359,12 @@ export declare class CollectionBrowser extends LitElement implements InfiniteScr
     connectedCallback(): void;
     disconnectedCallback(): void;
     handleResize(entry: ResizeObserverEntry): void;
+    /**
+     * Updates the data source with the current state of facet readiness for loading,
+     * so that they will begin to load in at the appropriate time according to the
+     * current facet loading strategy.
+     */
+    private updateFacetReadiness;
     /**
      * Sets up listeners for events that may require updating the left column height.
      */

package/dist/src/collection-browser.js

@@ -60,12 +60,6 @@ let CollectionBrowser = class CollectionBrowser extends LitElement {
          * If true, the `query` param will not be added to the URL or updated on query changes.
          */
         this.suppressURLQuery = false;
-        /**
-         * Whether to suppress the display of facets entirely.
-         * If true, the facet sidebar content will be replaced by a message that facets are
-         * temporarily unavailable.
-         */
-        this.suppressFacets = false;
         /**
          * Whether to suppress display of the sort bar.
          * If true, the entire sort bar (incl. display modes) will be omitted from rendering.
@@ -77,12 +71,21 @@ let CollectionBrowser = class CollectionBrowser extends LitElement {
          */
         this.suppressDisplayModes = false;
         /**
-         * Whether facets should be lazy-loaded.
-         * If false (default), facet data will be loaded eagerly along with search hits.
-         * If true, facet data will only be requested once the facet pane actually becomes visible,
-         * either by displaying in desktop mode or by the mobile facet dropdown being opened.
+         * What strategy to use for when/whether to load facet data for a search.
+         *
+         * Defaults to `eager`, always loading facets immediately alongside search results.
+         *
+         * To eliminate facets that are never seen, this can be reduced to `lazy-mobile`, which
+         * will delay loading facets in the mobile view until the "Filters" accordion is opened.
+         * Facets are still loaded eagerly when viewing the desktop layout.
+         *
+         * To further reduce facet requests for patrons who do not need to use them, this can be
+         * again reduced to `opt-in`, which will also require desktop users to explicitly request
+         * that they be loaded (in addition to the lazy mobile behavior described above).
+         *
+         * To entirely suppress facets from being loaded, this may be set to `off`.
          */
-        this.lazyLoadFacets = false;
+        this.facetLoadStrategy = 'eager';
         this.clearResultsOnEmptyQuery = false;
         this.collectionPagePath = '/details/';
         /** describes where this component is being used */
@@ -125,6 +128,7 @@ let CollectionBrowser = class CollectionBrowser extends LitElement {
          */
         this.searchResultsLoading = false;
         this.facetsLoading = false;
+        this.facetsOptedIn = false;
         this.mobileView = false;
         this.mobileFacetsVisible = false;
         this.defaultSortField = SortField.relevance;
@@ -711,11 +715,23 @@ let CollectionBrowser = class CollectionBrowser extends LitElement {
      * The template for the facets component alone, without any surrounding wrappers.
      */
     get facetsTemplate() {
-        if (this.suppressFacets) {
+        if (this.facetLoadStrategy === 'off') {
             return html `
         <p class="facets-message">
           ${msg('Facets are temporarily unavailable.')}
         </p>
+      `;
+        }
+        if (this.facetLoadStrategy === 'opt-in' && !this.facetsOptedIn) {
+            return html `
+        <button
+          class="facets-opt-in"
+          @click=${() => {
+                this.facetsOptedIn = true;
+            }}
+        >
+          ${msg('Load facets')}
+        </button>
       `;
         }
         return html `
@@ -953,10 +969,7 @@ let CollectionBrowser = class CollectionBrowser extends LitElement {
         if (changed.has('selectedCreatorFilter')) {
             this.sendFilterByCreatorAnalytics(changed.get('selectedCreatorFilter'));
         }
-        // Facets are always visible in the desktop view.
-        // But in the mobile view, their visibility state can be toggled by the user.
-        // In either case, inform the data source so that it can determine whether/when to fetch facets.
-        this.dataSource.handleFacetVisibilityChange(!this.mobileView || this.mobileFacetsVisible);
+        this.updateFacetReadiness();
         if (changed.has('baseQuery') ||
             changed.has('searchType') ||
             changed.has('selectedTitleFilter') ||
@@ -1031,6 +1044,20 @@ let CollectionBrowser = class CollectionBrowser extends LitElement {
         // Ensure the facet sidebar remains sized correctly
         this.updateLeftColumnHeight();
     }
+    /**
+     * Updates the data source with the current state of facet readiness for loading,
+     * so that they will begin to load in at the appropriate time according to the
+     * current facet loading strategy.
+     */
+    updateFacetReadiness() {
+        // In desktop view, we are always ready to load facets *unless* we are
+        // using the `opt-in` strategy and the opt-in has not yet occurred.
+        const desktopFacetsReady = !this.mobileView &&
+            (this.facetLoadStrategy !== 'opt-in' || this.facetsOptedIn);
+        // In mobile view, facets are considered ready provided they are currently visible (their dropdown is opened).
+        const mobileFacetsReady = this.mobileView && this.mobileFacetsVisible;
+        this.dataSource.handleFacetReadinessChange(desktopFacetsReady || mobileFacetsReady);
+    }
     /**
      * Sets up listeners for events that may require updating the left column height.
      */
@@ -1124,7 +1151,11 @@ let CollectionBrowser = class CollectionBrowser extends LitElement {
         const { visibleCellIndices } = e.detail;
         if (visibleCellIndices.length === 0)
             return;
-        const lastVisibleCellIndex = visibleCellIndices[visibleCellIndices.length - 1];
+        // 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];
         const lastVisibleCellPage = Math.floor(lastVisibleCellIndex / this.pageSize) + 1;
         if (this.currentPage !== lastVisibleCellPage) {
             this.currentPage = lastVisibleCellPage;
@@ -1906,9 +1937,6 @@ __decorate([
 __decorate([
     property({ type: Boolean })
 ], CollectionBrowser.prototype, "suppressURLQuery", void 0);
-__decorate([
-    property({ type: Boolean })
-], CollectionBrowser.prototype, "suppressFacets", void 0);
 __decorate([
     property({ type: Boolean })
 ], CollectionBrowser.prototype, "suppressSortBar", void 0);
@@ -1916,8 +1944,8 @@ __decorate([
     property({ type: Boolean })
 ], CollectionBrowser.prototype, "suppressDisplayModes", void 0);
 __decorate([
-    property({ type: Boolean })
-], CollectionBrowser.prototype, "lazyLoadFacets", void 0);
+    property({ type: String })
+], CollectionBrowser.prototype, "facetLoadStrategy", void 0);
 __decorate([
     property({ type: Boolean })
 ], CollectionBrowser.prototype, "clearResultsOnEmptyQuery", void 0);
@@ -1972,6 +2000,9 @@ __decorate([
 __decorate([
     state()
 ], CollectionBrowser.prototype, "facetsLoading", void 0);
+__decorate([
+    state()
+], CollectionBrowser.prototype, "facetsOptedIn", void 0);
 __decorate([
     state()
 ], CollectionBrowser.prototype, "totalResults", void 0);