@internetarchive/collection-browser 4.5.1 → 4.6.0

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/data-source/collection-browser-query-state.ts

@@ -0,0 +1,60 @@
+import type {
+  CollectionExtraInfo,
+  PageElementName,
+  SearchServiceInterface,
+  SearchType,
+  SortDirection,
+  SortParam,
+} from '@internetarchive/search-service';
+import type { FacetLoadStrategy, SelectedFacets, SortField } from '../models';
+import type { CollectionBrowserDataSourceInterface } from './collection-browser-data-source-interface';
+
+/**
+ * Properties of collection browser that affect the overall search query
+ */
+export interface CollectionBrowserQueryState {
+  baseQuery?: string;
+  identifiers?: string[];
+  withinCollection?: string;
+  withinProfile?: string;
+  profileElement?: PageElementName;
+  searchType: SearchType;
+  selectedFacets?: SelectedFacets;
+  internalFilters?: SelectedFacets;
+  minSelectedDate?: string;
+  maxSelectedDate?: string;
+  selectedTitleFilter: string | null;
+  selectedCreatorFilter: string | null;
+  selectedSort?: SortField;
+  sortDirection: SortDirection | null;
+}
+
+/**
+ * Interface representing search-related state and operations required by the
+ * data source on its host component.
+ */
+export interface CollectionBrowserSearchInterface
+  extends CollectionBrowserQueryState {
+  searchService?: SearchServiceInterface;
+  isTVCollection: boolean;
+  readonly sortParam: SortParam | null;
+  readonly defaultSortField: SortField | null;
+  readonly defaultSortDirection: SortDirection | null;
+  readonly facetLoadStrategy: FacetLoadStrategy;
+  readonly initialPageNumber: number;
+  readonly maxPagesToManage: number;
+  readonly currentVisiblePageNumbers: number[];
+  readonly clearResultsOnEmptyQuery?: boolean;
+  readonly dataSource?: CollectionBrowserDataSourceInterface;
+
+  getSessionId(): Promise<string>;
+  setSearchResultsLoading(loading: boolean): void;
+  setFacetsLoading(loading: boolean): void;
+  setTotalResultCount(count: number): void;
+  setTileCount(count: number): void;
+  applyDefaultCollectionSort(collectionInfo?: CollectionExtraInfo): void;
+  emitEmptyResults(): void;
+  emitSearchError(): void;
+  emitQueryStateChanged(): void;
+  refreshVisibleResults(): void;
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/data-source/models.ts

@@ -0,0 +1,56 @@
+import type {
+  PageElementName,
+  PageType,
+} from '@internetarchive/search-service';
+
+/**
+ * A Map from collection identifiers to their corresponding collection titles.
+ */
+export type CollectionTitles = Map<string, string>;
+
+/**
+ * A Map from channel names to their corresponding, more human-readable network name.
+ */
+export type TVChannelAliases = Map<string, string>;
+
+/**
+ * A Map from program (show) names to a mapping of all the channels that run them.
+ */
+export type TVProgramChannels = Map<string, Record<string, number>>;
+
+/**
+ * Object storing the different TV channel mappings used by the data source.
+ */
+export type TVChannelMaps = {
+  channelToNetwork?: TVChannelAliases;
+  programToChannels?: TVProgramChannels;
+};
+
+/**
+ * The subset of search service params that uniquely specify the type of results
+ * that are sought by an instance of collection browser.
+ */
+export type PageSpecifierParams = {
+  /**
+   * What high-level type of page is being fetched for (search results, collection, or profile)
+   */
+  pageType: PageType;
+  /**
+   * The target identifier for collection or profile pages (e.g., "prelinger", "@brewster", ...)
+   */
+  pageTarget?: string;
+  /**
+   * Which specific elements of a profile page to fetch. Corresponds to individual tab data
+   * (e.g., "uploads", "reviews", ...)
+   */
+  pageElements?: PageElementName[];
+};
+
+/**
+ * List of profile page elements that do not currently allow faceting
+ */
+export const FACETLESS_PAGE_ELEMENTS: PageElementName[] = [
+  'forum_posts',
+  'lending',
+  'web_archives',
+];

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/empty-placeholder.ts

@@ -0,0 +1,192 @@
+import {
+  css,
+  html,
+  LitElement,
+  CSSResultGroup,
+  nothing,
+  TemplateResult,
+} from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { choose } from 'lit/directives/choose.js';
+import { msg } from '@lit/localize';
+
+import emptyQueryIcon from './assets/img/icons/empty-query';
+import nullResultIcon from './assets/img/icons/null-result';
+
+export type PlaceholderType =
+  | 'empty-query'
+  | 'empty-collection'
+  | 'no-results'
+  | 'query-error'
+  | 'collection-error'
+  | null;
+@customElement('empty-placeholder')
+export class EmptyPlaceholder extends LitElement {
+  private static readonly MESSAGE_EMPTY_QUERY = msg(
+    'To begin searching, enter a search term in the box above and hit "Go".',
+  );
+
+  private static readonly MESSAGE_NO_SEARCH_RESULTS = msg(
+    'Your search did not match any items in the Archive. ' +
+      'Try different keywords or a more general search.',
+  );
+
+  private static readonly MESSAGE_NO_COLLECTION_RESULTS = msg(
+    'Your search did not match any items in this collection. ' +
+      'Try different keywords or a more general search.',
+  );
+
+  private static readonly MESSAGE_NO_VIEWABLE_MEMBERS = msg(
+    'This collection contains no viewable items.',
+  );
+
+  private static readonly MESSAGE_QUERY_ERROR = msg(
+    html`The search engine encountered an error, which might be related to your
+      search query.
+      <a
+        href="https://help.archive.org/help/search-building-powerful-complex-queries/"
+      >
+        Tips for constructing search queries.
+      </a> `,
+  );
+
+  private static readonly MESSAGE_COLLECTION_ERROR = msg(
+    html`The search engine encountered an error while loading this collection.
+      If the problem persists, please let us know at
+      <a href="mailto:info@archive.org">info@archive.org</a>.`,
+  );
+
+  private static readonly QUERY_ERROR_DETAILS_MESSAGE = msg('Error details:');
+
+  @property({ type: String }) placeholderType: PlaceholderType = null;
+
+  @property({ type: Boolean }) isMobileView?: false;
+
+  @property({ type: Boolean }) isCollection?: false;
+
+  @property({ type: String }) detailMessage?: string = '';
+
+  render() {
+    return this.placeholderType ? html`${this.placeholderTemplate}` : nothing;
+  }
+
+  private get placeholderTemplate(): TemplateResult {
+    return html`
+      <div
+        class="placeholder ${this.placeholderType} ${this.isMobileView
+          ? 'mobile'
+          : 'desktop'}"
+      >
+        ${choose(this.placeholderType, [
+          ['empty-query', () => this.emptyQueryTemplate],
+          ['empty-collection', () => this.emptyCollectionTemplate],
+          ['no-results', () => this.noResultsTemplate],
+          ['query-error', () => this.queryErrorTemplate],
+          ['collection-error', () => this.collectionErrorTemplate],
+        ])}
+      </div>
+    `;
+  }
+
+  private get emptyQueryTemplate(): TemplateResult {
+    // Added data-testid for Playwright testing
+    return html`
+      <h2 class="title" data-testid="empty-query-text-msg">
+        ${EmptyPlaceholder.MESSAGE_EMPTY_QUERY}
+      </h2>
+      <div>${emptyQueryIcon}</div>
+    `;
+  }
+
+  private get emptyCollectionTemplate(): TemplateResult {
+    // Added data-testid for Playwright testing
+    return html`
+      <h2 class="title" data-testid="empty-collection-text-msg">
+        ${EmptyPlaceholder.MESSAGE_NO_VIEWABLE_MEMBERS}
+      </h2>
+      <div>${nullResultIcon}</div>
+    `;
+  }
+
+  private get noResultsTemplate(): TemplateResult {
+    // Added data-testid for Playwright testing
+    return html`
+      <h2 class="title" data-testid="empty-results-text-msg">
+        ${this.isCollection
+          ? EmptyPlaceholder.MESSAGE_NO_COLLECTION_RESULTS
+          : EmptyPlaceholder.MESSAGE_NO_SEARCH_RESULTS}
+      </h2>
+      <div>${nullResultIcon}</div>
+    `;
+  }
+
+  private get queryErrorTemplate(): TemplateResult {
+    // Added data-testid for Playwright testing
+    return html`
+      <h2 class="title" data-testid="error-query-text-msg">
+        ${EmptyPlaceholder.MESSAGE_QUERY_ERROR}
+      </h2>
+      <div>${nullResultIcon}</div>
+      <p class="error-details">
+        ${EmptyPlaceholder.QUERY_ERROR_DETAILS_MESSAGE} ${this.detailMessage}
+      </p>
+    `;
+  }
+
+  private get collectionErrorTemplate(): TemplateResult {
+    // Added data-testid for Playwright testing
+    return html`
+      <h2 class="title" data-testid="error-collection-text-msg">
+        ${EmptyPlaceholder.MESSAGE_COLLECTION_ERROR}
+      </h2>
+      <div>${nullResultIcon}</div>
+      <p class="error-details">
+        ${EmptyPlaceholder.QUERY_ERROR_DETAILS_MESSAGE} ${this.detailMessage}
+      </p>
+    `;
+  }
+
+  static get styles(): CSSResultGroup {
+    return css`
+      :host {
+        text-align: center;
+        width: 100%;
+      }
+
+      a {
+        text-decoration: none;
+      }
+      a:link {
+        color: var(--ia-theme-link-color, #4b64ff);
+      }
+      a:hover {
+        text-decoration: underline;
+      }
+
+      .placeholder {
+        display: block;
+      }
+
+      .desktop svg {
+        max-height: 40rem;
+      }
+      .desktop .title,
+      .desktop .error-details {
+        margin: 4rem 0;
+      }
+
+      .mobile svg {
+        max-height: 20rem;
+      }
+      .mobile .title,
+      .mobile .error-details {
+        margin: 2rem 0.5;
+      }
+
+      .error-details {
+        font-size: 1.2rem;
+        word-break: break-word;
+      }
+    `;
+  }
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/expanded-date-picker.ts

@@ -0,0 +1,191 @@
+import {
+  css,
+  html,
+  LitElement,
+  CSSResultGroup,
+  TemplateResult,
+  nothing,
+} from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import { msg } from '@lit/localize';
+import type { ModalManagerInterface } from '@internetarchive/modal-manager';
+import type { AnalyticsManagerInterface } from '@internetarchive/analytics-manager';
+import {
+  BarScalingOption,
+  BinSnappingInterval,
+} from '@internetarchive/histogram-date-range';
+import {
+  analyticsActions,
+  analyticsCategories,
+} from './utils/analytics-events';
+
+import '@internetarchive/histogram-date-range';
+
+@customElement('expanded-date-picker')
+export class ExpandedDatePicker extends LitElement {
+  @property({ type: String }) minDate?: string;
+
+  @property({ type: String }) maxDate?: string;
+
+  @property({ type: String }) minSelectedDate?: string;
+
+  @property({ type: String }) maxSelectedDate?: string;
+
+  @property({ type: Array }) buckets?: number[];
+
+  @property({ type: String }) customDateFormat?: string;
+
+  @property({ type: String }) customTooltipDateFormat?: string;
+
+  @property({ type: String }) customTooltipLabel?: string;
+
+  @property({ type: String }) binSnapping: BinSnappingInterval = 'none';
+
+  @property({ type: String }) barScaling: BarScalingOption = 'logarithmic';
+
+  @property({ type: Object, attribute: false })
+  modalManager?: ModalManagerInterface;
+
+  @property({ type: Object, attribute: false })
+  analyticsHandler?: AnalyticsManagerInterface;
+
+  render(): TemplateResult {
+    return html`
+      <div id="container">
+        <histogram-date-range
+          id="date-picker"
+          .minDate=${this.minDate}
+          .maxDate=${this.maxDate}
+          .minSelectedDate=${this.minSelectedDate ?? this.minDate}
+          .maxSelectedDate=${this.maxSelectedDate ?? this.maxDate}
+          dateFormat=${ifDefined(this.customDateFormat)}
+          tooltipDateFormat=${ifDefined(this.customTooltipDateFormat)}
+          tooltipLabel=${ifDefined(this.customTooltipLabel)}
+          .binSnapping=${this.binSnapping}
+          .barScaling=${this.barScaling ?? nothing}
+          .updateDelay=${0}
+          updateWhileFocused
+          missingDataMessage="..."
+          .width=${560}
+          .height=${120}
+          .bins=${this.buckets}
+          @histogramDateRangeUpdated=${this.histogramDateRangeUpdated}
+        >
+          <button
+            id="apply-btn"
+            slot="inputs-right-side"
+            @click=${this.applyBtnClicked}
+          >
+            ${msg('Apply date range')}
+          </button>
+        </histogram-date-range>
+      </div>
+    `;
+  }
+
+  connectedCallback(): void {
+    super.connectedCallback?.();
+    this.setupEscapeListener();
+  }
+
+  disconnectedCallback(): void {
+    super.disconnectedCallback?.();
+    this.removeEscapeListener();
+  }
+
+  /**
+   * Add an event listener to close the date picker modal when the Esc key is pressed
+   */
+  private setupEscapeListener() {
+    document.addEventListener('keydown', this.boundEscapeListener);
+  }
+
+  /**
+   * Remove the Esc key listener that was previously added
+   */
+  private removeEscapeListener() {
+    document.removeEventListener('keydown', this.boundEscapeListener);
+  }
+
+  /**
+   * Closes the modal dialog if the given event is pressing the Esc key.
+   * Arrow function to ensure `this` remains bound to the current component.
+   */
+  private boundEscapeListener = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      this.closeModal();
+    }
+  };
+
+  /**
+   * When the histogram is updated, keep track of the newly selected date range.
+   * We don't commit to the new range until the apply button is clicked.
+   */
+  private histogramDateRangeUpdated(
+    e: CustomEvent<{
+      minDate: string;
+      maxDate: string;
+    }>,
+  ): void {
+    this.minSelectedDate = e.detail.minDate;
+    this.maxSelectedDate = e.detail.maxDate;
+  }
+
+  /**
+   * When the Apply button is clicked, emit the current date range and close the modal.
+   */
+  private applyBtnClicked(): void {
+    const event = new CustomEvent('histogramDateRangeApplied', {
+      detail: {
+        minDate: this.minSelectedDate,
+        maxDate: this.maxSelectedDate,
+      },
+    });
+    this.dispatchEvent(event);
+    this.closeModal();
+
+    this.analyticsHandler?.sendEvent({
+      category: analyticsCategories.default,
+      action: analyticsActions.histogramChangedFromModal,
+      label: window.location.href,
+    });
+  }
+
+  /**
+   * Closes the modal associated with this component (if it exists) and dispatches a
+   * modalClosed event.
+   */
+  private closeModal(): void {
+    if (this.modalManager) {
+      this.modalManager.closeModal();
+      this.dispatchEvent(new CustomEvent('modalClosed'));
+    }
+  }
+
+  static get styles(): CSSResultGroup {
+    return css`
+      #container {
+        display: flex;
+        justify-content: center;
+        padding: 40px 10px 10px;
+        overflow: hidden;
+      }
+
+      #date-picker {
+        --histogramDateRangeInputWidth: 50px;
+        --histogramDateRangeInputRowMargin: 5px 0 0 0;
+      }
+
+      #apply-btn {
+        margin: 0 0 0 5px;
+        padding: 8px 10px;
+        border: 0;
+        border-radius: 4px;
+        background: var(--primaryButtonBGColor, #194880);
+        color: white;
+        cursor: pointer;
+      }
+    `;
+  }
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/language-code-handler/language-code-handler.ts

@@ -0,0 +1,64 @@
+import { codeToLanguageMap } from './language-code-mapping';
+
+// To serialize the list of potential language codes, we store
+// the string in the format `en-us|en|en-gb` with `|` being the separator.
+// This allows us to generate a query of `language:(en-us OR en OR en-gb)`
+// when we deserialize the string.
+export interface LanguageCodeHandlerInterface {
+  /**
+   * This takes a list of codes in the format `en-us|en|en-gb` and
+   * returns the first language code in the list.
+   *
+   * The codes in the string should always represent the same language name.
+   * eg `en-us`, `en-gb`, and `en` should always be "English"
+   *
+   * @param languageCodes
+   */
+  getLanguageNameFromCodeString(languageCodes: string): string;
+
+  /**
+   * This creates a serialized string of language codes for the given language.
+   *
+   * eg. `English` becomes `en-us|en|en-gb|.....`
+   *
+   * @param languageName
+   */
+  getCodeStringFromLanguageName(languageName: string): string;
+
+  /**
+   * Get an array of langauge codes from a serialized string.
+   *
+   * eg. `en-us|en|en-gb` becomes `['en-us', 'en', 'en-gb']`
+   *
+   * @param languageCodes
+   */
+  getCodeArrayFromCodeString(languageCodes: string): string[];
+}
+
+export class LanguageCodeHandler implements LanguageCodeHandlerInterface {
+  private delimeter = '|';
+
+  /** @inheritdoc */
+  getLanguageNameFromCodeString(languageCodes: string): string {
+    const split = this.getCodeArrayFromCodeString(languageCodes);
+    if (split.length === 0) return '';
+    const languageCode = split[0];
+    const languageName = codeToLanguageMap[languageCode];
+    return languageName ?? languageCodes;
+  }
+
+  /** @inheritdoc */
+  getCodeStringFromLanguageName(languageName: string): string {
+    const languageCodes = Object.keys(codeToLanguageMap).filter(
+      code => codeToLanguageMap[code] === languageName,
+    );
+    const stringifiedCodes = languageCodes?.join(this.delimeter);
+    return stringifiedCodes;
+  }
+
+  /** @inheritdoc */
+  getCodeArrayFromCodeString(languageCodes: string): string[] {
+    const split = languageCodes.split(this.delimeter);
+    return split;
+  }
+}