@internetarchive/collection-browser 0.2.18 → 0.2.20-alpha.1

package/src/app-root.ts

@@ -1,10 +1,17 @@
+import {
+  AnalyticsEvent,
+  AnalyticsManager,
+} from '@internetarchive/analytics-manager';
 import { SearchService } from '@internetarchive/search-service';
 import { LocalCache } from '@internetarchive/local-cache';
 import { html, css, LitElement, PropertyValues } from 'lit';
-import { customElement, query, state } from 'lit/decorators.js';
+import { customElement, property, query, state } from 'lit/decorators.js';
 import { SharedResizeObserver } from '@internetarchive/shared-resize-observer';
 import { CollectionNameCache } from '@internetarchive/collection-name-cache';
+
+import type { AnalyticsManagerInterface } from '@internetarchive/analytics-manager';
 import type { CollectionBrowser } from '../src/collection-browser';
+
 import '../src/collection-browser';
 
 @customElement('app-root')
@@ -34,12 +41,28 @@ export class AppRoot extends LitElement {
 
   @state() private loggedIn: boolean = false;
 
+  @property({ type: Object, reflect: false }) latestAction?: AnalyticsEvent;
+
   @query('#base-query-field') private baseQueryField!: HTMLInputElement;
 
   @query('#page-number-input') private pageNumberInput!: HTMLInputElement;
 
   @query('collection-browser') private collectionBrowser!: CollectionBrowser;
 
+  private analyticsManager = new AnalyticsManager();
+
+  private analyticsHandler: AnalyticsManagerInterface = {
+    sendPing: this.sendAnalytics.bind(this),
+    sendEvent: this.sendAnalytics.bind(this),
+    sendEventNoSampling: this.sendAnalytics.bind(this),
+  };
+
+  private sendAnalytics(ae: AnalyticsEvent) {
+    console.log('Analytics Received ----', ae);
+    this.latestAction = ae;
+    this.analyticsManager?.sendEventNoSampling(ae);
+  }
+
   private searchPressed(e: Event) {
     e.preventDefault();
     this.searchQuery = this.baseQueryField.value;
@@ -54,7 +77,7 @@ export class AppRoot extends LitElement {
     this.collectionBrowser.goToPage(this.currentPage);
   }
 
-  protected updated(changed: PropertyValues): void {
+  protected override updated(changed: PropertyValues): void {
     if (changed.has('currentPage') && this.currentPage) {
       this.pageNumberInput.value = this.currentPage.toString();
     }
@@ -86,6 +109,23 @@ export class AppRoot extends LitElement {
           <input type="submit" value="Go" />
         </form>
 
+        <div id="last-event">
+          <button
+            @click=${() => {
+              const details = this.shadowRoot?.getElementById(
+                'latest-event-details'
+              );
+              details?.classList.toggle('hidden');
+            }}
+          >
+            Last Event Captured
+          </button>
+          <pre id="latest-event-details">
+            ${JSON.stringify(this.latestAction, null, 2)}
+          </pre
+          >
+        </div>
+
         <div id="cell-controls">
           <div id="cell-size-control">
             <div>
@@ -130,6 +170,14 @@ export class AppRoot extends LitElement {
                 @click=${this.loginChanged}
               />
             </div>
+            <div>
+              <label for="show-dummy-snippets">Show dummy snippets:</label>
+              <input
+                type="checkbox"
+                id="show-dummy-snippets"
+                @click=${this.snippetsChanged}
+              />
+            </div>
           </div>
           <div id="cell-gap-control">
             <div>
@@ -171,6 +219,7 @@ export class AppRoot extends LitElement {
           .collectionNameCache=${this.collectionNameCache}
           .showHistogramDatePicker=${true}
           .loggedIn=${this.loggedIn}
+          .analyticsHandler=${this.analyticsHandler}
           @visiblePageChanged=${this.visiblePageChanged}
           @baseQueryChanged=${this.baseQueryChanged}
         >
@@ -206,6 +255,48 @@ export class AppRoot extends LitElement {
     }
   }
 
+  private async snippetsChanged(e: Event) {
+    const target = e.target as HTMLInputElement;
+    if (target.checked) {
+      // Decorate the default search service with a wrapper that adds
+      // dummy snippets to any successful searches
+      this.searchService = {
+        ...SearchService.default,
+        async search(params) {
+          const result = await SearchService.default.search(params);
+          result.success?.response.docs.forEach(doc => {
+            const metadata = doc.rawMetadata;
+            if (metadata) {
+              metadata.snippets = [
+                'this is a text {{{snippet}}} block with potentially',
+                'multiple {{{snippets}}} and such',
+                'but the {{{snippet}}} block may be quite long perhaps',
+                'depending on how many {{{snippet}}} matches there are',
+                'there may be multiple lines of {{{snippets}}} to show',
+                'but each {{{snippet}}} should be relatively short',
+                'and {{{snippets}}} are each a {{{snippet}}} of text',
+                'but every {{{snippet}}} might have multiple matches',
+                'the {{{snippets}}} should be separated and surrounded by ellipses',
+              ];
+            }
+          });
+          return result;
+        },
+      };
+    } else {
+      // Restore the default seach service
+      this.searchService = SearchService.default;
+    }
+
+    // Re-perform the current search to show/hide the snippets immediately
+    const oldQuery = this.searchQuery;
+    this.searchQuery = ''; // Should just reset to the placeholder
+    await this.updateComplete;
+    // For unclear reasons, Safari refuses to re-apply the old query until the next tick, hence:
+    await new Promise(res => setTimeout(res, 0));
+    this.searchQuery = oldQuery; // Re-apply the original query
+  }
+
   private rowGapChanged(e: Event) {
     const input = e.target as HTMLInputElement;
     this.rowGap = parseFloat(input.value);
@@ -293,5 +384,15 @@ export class AppRoot extends LitElement {
     #cell-gap-control {
       margin-left: 1rem;
     }
+
+    #last-event {
+      background-color: aliceblue;
+      padding: 5px;
+      margin: 5px auto;
+    }
+
+    .hidden {
+      display: none;
+    }
   `;
 }

package/src/collection-browser.ts

@@ -9,6 +9,8 @@ import {
 } from 'lit';
 import { customElement, property, query, state } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
+
+import type { AnalyticsManagerInterface } from '@internetarchive/analytics-manager';
 import type {
   InfiniteScroller,
   InfiniteScrollerCellProviderInterface,
@@ -41,6 +43,7 @@ import {
   defaultSelectedFacets,
   TileModel,
   CollectionDisplayMode,
+  FacetOption,
 } from './models';
 import {
   RestorationStateHandlerInterface,
@@ -52,6 +55,11 @@ import { LanguageCodeHandler } from './language-code-handler/language-code-handl
 import type { PlaceholderType } from './empty-placeholder';
 import './empty-placeholder';
 
+import {
+  analyticsActions,
+  analyticsCategories,
+} from './utils/analytics-events';
+
 @customElement('collection-browser')
 export class CollectionBrowser
   extends LitElement
@@ -155,6 +163,9 @@ export class CollectionBrowser
 
   private languageCodeHandler = new LanguageCodeHandler();
 
+  @property({ type: Object, attribute: false })
+  private analyticsHandler?: AnalyticsManagerInterface;
+
   /**
    * When we're animated scrolling to the page, we don't want to fetch
    * all of the pages as it scrolls so this lets us know if we're scrolling
@@ -295,7 +306,9 @@ export class CollectionBrowser
                 ? this.totalResults.toLocaleString()
                 : '-'}
             </span>
-            <span id="big-results-label">Results</span>
+            <span id="big-results-label">
+              ${this.totalResults === 1 ? 'Result' : 'Results'}
+            </span>
           </div>
         </div>
         <div
@@ -328,18 +341,21 @@ export class CollectionBrowser
   }
 
   private get sortFilterBarTemplate() {
-    return html`<sort-filter-bar
-      .selectedSort=${this.selectedSort}
-      .sortDirection=${this.sortDirection}
-      .displayMode=${this.displayMode}
-      .selectedTitleFilter=${this.selectedTitleFilter}
-      .selectedCreatorFilter=${this.selectedCreatorFilter}
-      .resizeObserver=${this.resizeObserver}
-      @sortChanged=${this.userChangedSort}
-      @displayModeChanged=${this.displayModeChanged}
-      @titleLetterChanged=${this.titleLetterSelected}
-      @creatorLetterChanged=${this.creatorLetterSelected}
-    ></sort-filter-bar>`;
+    return html`
+      <sort-filter-bar
+        .selectedSort=${this.selectedSort}
+        .sortDirection=${this.sortDirection}
+        .displayMode=${this.displayMode}
+        .selectedTitleFilter=${this.selectedTitleFilter}
+        .selectedCreatorFilter=${this.selectedCreatorFilter}
+        .resizeObserver=${this.resizeObserver}
+        @sortChanged=${this.userChangedSort}
+        @displayModeChanged=${this.displayModeChanged}
+        @titleLetterChanged=${this.titleLetterSelected}
+        @creatorLetterChanged=${this.creatorLetterSelected}
+      >
+      </sort-filter-bar>
+    `;
   }
 
   private userChangedSort(
@@ -358,12 +374,25 @@ export class CollectionBrowser
     this.currentPage = 1;
   }
 
-  private selectedSortChanged() {
+  private sendSortByAnaltyics(prevSortDirection: SortDirection | null): void {
+    const directionCleared = prevSortDirection && !this.sortDirection;
+
+    this.analyticsHandler?.sendEventNoSampling({
+      category: analyticsCategories.default,
+      action: analyticsActions.sortBy,
+      label: `${this.selectedSort}${
+        this.sortDirection || directionCleared ? `-${this.sortDirection}` : ''
+      }`,
+    });
+  }
+
+  private selectedSortChanged(): void {
     if (this.selectedSort === 'relevance' || this.sortDirection === null) {
       this.sortParam = null;
       return;
     }
     const sortField = SortFieldToMetadataField[this.selectedSort];
+
     if (!sortField) return;
     this.sortParam = { field: sortField, direction: this.sortDirection };
   }
@@ -372,15 +401,61 @@ export class CollectionBrowser
     e: CustomEvent<{ displayMode: CollectionDisplayMode }>
   ) {
     this.displayMode = e.detail.displayMode;
+
+    if (this.displayMode) {
+      this.analyticsHandler?.sendEventNoSampling({
+        category: analyticsCategories.default,
+        action: analyticsActions.displayMode,
+        label: this.displayMode,
+      });
+    }
+  }
+
+  /** 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;
+    }
+    const cleared = prevSelectedLetter && this.selectedTitleFilter === null;
+
+    this.analyticsHandler?.sendEventNoSampling({
+      category: analyticsCategories.default,
+      action: analyticsActions.filterByTitle,
+      label: cleared
+        ? `clear-${prevSelectedLetter}`
+        : `${prevSelectedLetter || 'start'}-${this.selectedTitleFilter}`,
+    });
   }
 
-  private selectedTitleLetterChanged() {
+  private selectedTitleLetterChanged(): void {
     this.titleQuery = this.selectedTitleFilter
       ? `firstTitle:${this.selectedTitleFilter}`
       : undefined;
   }
 
-  private selectedCreatorLetterChanged() {
+  /** Send Analytics when filtering by creator's first letter
+   * labels: 'start-<ToLetter>' | 'clear-<FromLetter>' | '<FromLetter>-<ToLetter>'
+   * */
+  private sendFilterByCreatorAnalytics(
+    prevSelectedLetter: string | null
+  ): void {
+    if (!prevSelectedLetter && !this.selectedCreatorFilter) {
+      return;
+    }
+    const cleared = prevSelectedLetter && this.selectedCreatorFilter === null;
+
+    this.analyticsHandler?.sendEventNoSampling({
+      category: analyticsCategories.default,
+      action: analyticsActions.filterByCreator,
+      label: cleared
+        ? `clear-${prevSelectedLetter}`
+        : `${prevSelectedLetter || 'start'}-${this.selectedCreatorFilter}`,
+    });
+  }
+
+  private selectedCreatorLetterChanged(): void {
     this.creatorQuery = this.selectedCreatorFilter
       ? `firstCreator:${this.selectedCreatorFilter}`
       : undefined;
@@ -439,7 +514,10 @@ export class CollectionBrowser
         ?collapsableFacets=${this.mobileView}
         ?facetsLoading=${this.facetDataLoading}
         ?fullYearAggregationLoading=${this.fullYearAggregationLoading}
-      ></collection-facets>
+        .onFacetClick=${this.facetClickHandler}
+        .analyticsHandler=${this.analyticsHandler}
+      >
+      </collection-facets>
     `;
   }
 
@@ -489,6 +567,14 @@ export class CollectionBrowser
   ) {
     const { minDate, maxDate } = e.detail;
     this.dateRangeQueryClause = `year:[${minDate} TO ${maxDate}]`;
+
+    if (this.dateRangeQueryClause) {
+      this.analyticsHandler?.sendEventNoSampling({
+        category: analyticsCategories.default,
+        action: analyticsActions.histogramChanged,
+        label: this.dateRangeQueryClause,
+      });
+    }
   }
 
   firstUpdated(): void {
@@ -523,12 +609,20 @@ export class CollectionBrowser
       this.handleQueryChange();
     }
     if (changed.has('selectedSort') || changed.has('sortDirection')) {
+      const prevSortDirection = changed.get('sortDirection') as SortDirection;
+      this.sendSortByAnaltyics(prevSortDirection);
       this.selectedSortChanged();
     }
     if (changed.has('selectedTitleFilter')) {
+      this.sendFilterByTitleAnalytics(
+        changed.get('selectedTitleFilter') as string
+      );
       this.selectedTitleLetterChanged();
     }
     if (changed.has('selectedCreatorFilter')) {
+      this.sendFilterByCreatorAnalytics(
+        changed.get('selectedCreatorFilter') as string
+      );
       this.selectedCreatorLetterChanged();
     }
     if (changed.has('pagesToRender')) {
@@ -748,6 +842,7 @@ export class CollectionBrowser
   private get facetQuery(): string | undefined {
     if (!this.selectedFacets) return undefined;
     const facetQuery = [];
+    // console.log('selectedFacets: ', this.selectedFacets);
     for (const [facetName, facetValues] of Object.entries(
       this.selectedFacets
     )) {
@@ -778,6 +873,30 @@ export class CollectionBrowser
     this.selectedFacets = e.detail;
   }
 
+  facetClickHandler(
+    name: FacetOption,
+    facetSelected: boolean,
+    negative: boolean
+  ): void {
+    if (negative) {
+      this.analyticsHandler?.sendEventNoSampling({
+        category: analyticsCategories.default,
+        action: facetSelected
+          ? analyticsActions.facetNegativeSelected
+          : analyticsActions.facetNegativeDeselected,
+        label: name,
+      });
+    } else {
+      this.analyticsHandler?.sendEventNoSampling({
+        category: analyticsCategories.default,
+        action: facetSelected
+          ? analyticsActions.facetSelected
+          : analyticsActions.facetDeselected,
+        label: name,
+      });
+    }
+  }
+
   private async fetchFacets() {
     if (!this.fullQuery) return;
 
@@ -1076,6 +1195,7 @@ export class CollectionBrowser
         issue: doc.issue?.value,
         itemCount: doc.item_count?.value ?? 0,
         mediatype: doc.mediatype?.value ?? 'data',
+        snippets: doc.snippets?.values ?? [],
         source: doc.source?.value,
         subjects: doc.subject?.values ?? [],
         title: this.etreeTitle(
@@ -1120,6 +1240,21 @@ export class CollectionBrowser
     return title ?? '';
   }
 
+  /** callback when a result is selected */
+  resultSelected(event: CustomEvent<TileModel>): void {
+    this.analyticsHandler?.sendEventNoSampling({
+      category: analyticsCategories.default,
+      action: analyticsActions.resultSelected,
+      label: event.detail.mediatype === 'collection' ? 'collection' : 'item',
+    });
+
+    this.analyticsHandler?.sendEventNoSampling({
+      category: analyticsCategories.default,
+      action: analyticsActions.resultSelected,
+      label: `page-${this.currentPage}`,
+    });
+  }
+
   cellForIndex(index: number): TemplateResult | undefined {
     const model = this.tileModelAtCellIndex(index);
     if (!model) return undefined;
@@ -1135,6 +1270,7 @@ export class CollectionBrowser
         .sortParam=${this.sortParam}
         .mobileBreakpoint=${this.mobileBreakpoint}
         .loggedIn=${this.loggedIn}
+        @resultSelected=${(e: CustomEvent) => this.resultSelected(e)}
       >
       </tile-dispatcher>
     `;

package/src/collection-facets.ts

@@ -79,6 +79,13 @@ export class CollectionFacets extends LitElement {
   @property({ type: Object })
   collectionNameCache?: CollectionNameCacheInterface;
 
+  /** Fires when a facet is clicked */
+  @property({ type: Function }) onFacetClick?: (
+    name: FacetOption,
+    facetChecked: boolean,
+    negative: boolean
+  ) => void;
+
   @state() openFacets: Record<FacetOption, boolean> = {
     subject: false,
     mediatype: false,
@@ -88,6 +95,7 @@ export class CollectionFacets extends LitElement {
     year: false,
   };
 
+  @property({ type: Object, attribute: false })
   render() {
     return html`
       <div id="container" class="${this.facetsLoading ? 'loading' : ''}">
@@ -426,7 +434,7 @@ export class CollectionFacets extends LitElement {
     `;
   }
 
-  private facetClicked(e: Event, bucket: FacetBucket, negative: boolean) {
+  private facetClicked(e: Event, bucket: FacetBucket, negative: boolean): void {
     const target = e.target as HTMLInputElement;
     const { checked, name, value } = target;
     if (checked) {
@@ -434,6 +442,10 @@ export class CollectionFacets extends LitElement {
     } else {
       this.facetUnchecked(name as FacetOption, value);
     }
+
+    if (this.onFacetClick) {
+      this.onFacetClick(name as FacetOption, checked, negative);
+    }
   }
 
   private facetChecked(key: FacetOption, value: string, negative: boolean) {

package/src/models.ts

@@ -19,6 +19,7 @@ export interface TileModel {
   itemCount: number;
   mediatype: MediaType;
   source?: string;
+  snippets?: string[];
   subjects: string[];
   title: string;
   viewCount: number;
@@ -158,3 +159,12 @@ export const defaultSelectedFacets: SelectedFacets = {
   collection: {},
   year: {},
 };
+
+export const mockedSelectedFacets: SelectedFacets = {
+  subject: {},
+  mediatype: { data: 'selected' },
+  language: {},
+  creator: {},
+  collection: {},
+  year: {},
+};

package/src/tiles/grid/item-tile.ts

@@ -1,5 +1,12 @@
 /* eslint-disable import/no-duplicates */
-import { css, CSSResultGroup, html, LitElement, nothing } from 'lit';
+import {
+  css,
+  CSSResultGroup,
+  html,
+  LitElement,
+  nothing,
+  TemplateResult,
+} from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import type { SortParam } from '@internetarchive/search-service';
@@ -8,6 +15,7 @@ import { formatDate } from '../../utils/format-date';
 import type { TileModel } from '../../models';
 
 import '../image-block';
+import '../text-snippet-block';
 import '../item-image';
 import '../mediatype-icon';
 import './tile-stats';
@@ -35,6 +43,7 @@ export class ItemTile extends LitElement {
           </div>
 
           <image-block 
+            class=${this.hasSnippets ? 'has-snippets' : nothing}
             .model=${this.model}
             .baseImageUrl=${this.baseImageUrl}
             .loggedIn=${this.loggedIn}
@@ -43,6 +52,8 @@ export class ItemTile extends LitElement {
             .viewSize=${'grid'}>
           </image-block>
 
+          ${this.textSnippetsTemplate}
+
           ${
             this.doesSortedByDate
               ? this.sortedDateInfoTemplate
@@ -109,6 +120,19 @@ export class ItemTile extends LitElement {
     `;
   }
 
+  private get textSnippetsTemplate(): TemplateResult | typeof nothing {
+    if (!this.hasSnippets) return nothing;
+
+    return html`<text-snippet-block
+      viewsize="grid"
+      .snippets=${this.model?.snippets}
+    ></text-snippet-block>`;
+  }
+
+  private get hasSnippets(): boolean {
+    return !!this.model?.snippets?.length;
+  }
+
   static get styles(): CSSResultGroup {
     return css`
       .container {
@@ -142,6 +166,16 @@ export class ItemTile extends LitElement {
         text-decoration: underline;
       }
 
+      image-block {
+        display: block;
+        margin-bottom: 5px;
+      }
+
+      image-block.has-snippets {
+        /* If there is a text snippet block present, the image block needs to shrink */
+        --imgBlockHeight: 11rem;
+      }
+
       .created-by,
       .date-sorted-by {
         display: flex;
@@ -149,7 +183,6 @@ export class ItemTile extends LitElement {
         align-items: flex-end; /* Important to start text from bottom */
         height: 3rem;
         padding-top: 1rem;
-        margin-top: 5px;
       }
 
       .truncated {

package/src/tiles/image-block.ts

@@ -90,7 +90,7 @@ export class ImageBlock extends LitElement {
       }
 
       .grid {
-        height: 16rem;
+        height: var(--imgBlockHeight, 16rem);
         flex: 1;
       }
 

package/src/tiles/list/tile-list.ts

@@ -140,7 +140,7 @@ export class TileList extends LitElement {
         ${this.viewsTemplate} ${this.ratingTemplate} ${this.reviewsTemplate}
       </div>
       ${this.topicsTemplate} ${this.collectionsTemplate}
-      ${this.descriptionTemplate}
+      ${this.descriptionTemplate} ${this.textSnippetsTemplate}
     `;
   }
 
@@ -292,6 +292,19 @@ export class TileList extends LitElement {
     );
   }
 
+  private get textSnippetsTemplate(): TemplateResult | typeof nothing {
+    if (!this.hasSnippets) return nothing;
+
+    return html`<text-snippet-block
+      viewsize="list"
+      .snippets=${this.model?.snippets}
+    ></text-snippet-block>`;
+  }
+
+  private get hasSnippets(): boolean {
+    return !!this.model?.snippets?.length;
+  }
+
   // Utility functions
   private metadataTemplate(text: any, label = '', id?: string) {
     if (!text) return nothing;