@internetarchive/collection-browser 4.5.2 → 4.6.0

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/tiles/tile-display-value-provider.ts

@@ -0,0 +1,133 @@
+import { TemplateResult, html, nothing } from 'lit';
+import { msg, str } from '@lit/localize';
+import type { SortParam } from '@internetarchive/search-service';
+import type { TileModel } from '../models';
+import { formatDate } from '../utils/format-date';
+
+/**
+ * A class encapsulating shared logic for converting model values into display values
+ * across different types of tiles.
+ */
+export class TileDisplayValueProvider {
+  private model?: TileModel;
+
+  private baseNavigationUrl?: string;
+
+  private collectionPagePath?: string;
+
+  private sortParam?: SortParam;
+
+  private creatorFilter?: string;
+
+  constructor(
+    options: {
+      model?: TileModel;
+      baseNavigationUrl?: string;
+      collectionPagePath?: string;
+      sortParam?: SortParam;
+      creatorFilter?: string;
+    } = {},
+  ) {
+    this.model = options.model;
+    this.baseNavigationUrl = options.baseNavigationUrl;
+    this.collectionPagePath = options.collectionPagePath ?? '/details/';
+    this.sortParam = options.sortParam;
+    this.creatorFilter = options.creatorFilter;
+  }
+
+  /**
+   * Examines the creator(s) for the given tile model, returning
+   * the first creator whose name matches the provided filter
+   * (or simply the first creator overall if no filter is provided).
+   */
+  get firstCreatorMatchingFilter(): string | undefined {
+    let matchingCreator;
+
+    // If we're filtering by creator initial and have multiple creators, we want
+    // to surface the first creator who matches the filter.
+    if (this.creatorFilter && this.model?.creators.length) {
+      const firstLetter = this.creatorFilter; // This is just to satisfy tsc
+      matchingCreator = this.model.creators.find(creator =>
+        // Decompose combining characters first, so that e.g., filtering on E matches É too.
+        // Then remove anything that isn't strictly alphabetic, since our filters currently
+        // only handle A-Z. The first such letter (if one exists) is what needs to match.
+        creator
+          .normalize('NFD')
+          .replace(/[^A-Z]+/gi, '')
+          .toUpperCase()
+          .startsWith(firstLetter),
+      );
+    }
+
+    return matchingCreator ?? this.model?.creator;
+  }
+
+  /**
+   * The label indicating what year an account item was created.
+   * E.g., "Archivist since 2015"
+   */
+  get accountLabel(): string {
+    return this.model?.dateAdded
+      ? msg(str`Archivist since ${this.model.dateAdded.getFullYear()}`)
+      : '';
+  }
+
+  /**
+   * The readable label for the current sort if it is a type of date sort,
+   * or the empty string otherwise.
+   */
+  get dateLabel(): string {
+    switch (this.sortParam?.field) {
+      case 'publicdate':
+        return msg('Archived');
+      case 'reviewdate':
+        return msg('Reviewed');
+      case 'addeddate':
+        return msg('Added');
+      case 'date':
+        return msg('Published');
+      default:
+        return '';
+    }
+  }
+
+  /**
+   * The readable label for the current views column, based on whether
+   * weekly or all-time views are being shown.
+   */
+  get viewsLabel(): string {
+    return this.sortParam?.field === 'week'
+      ? msg('Weekly views')
+      : msg('All-time views');
+  }
+
+  /**
+   * Produces a URL pointing at the item page for the given identifier,
+   * using the current base URL and the correct path based on whether the
+   * item is specified to be a collection (default false).
+   */
+  itemPageUrl(
+    identifier?: string,
+    isCollection = false,
+  ): string | typeof nothing {
+    if (!identifier || this.baseNavigationUrl == null) return nothing;
+    const basePath = isCollection ? this.collectionPagePath : '/details/';
+    return `${this.baseNavigationUrl}${basePath}${identifier}`;
+  }
+
+  /**
+   * Produces a template for a link to a single web capture of the given URL and date
+   */
+  webArchivesCaptureLink(url: string, date: Date): TemplateResult {
+    // Convert the date into the format used to identify wayback captures (e.g., '20150102124550')
+    const captureDateStr = date
+      .toISOString()
+      .replace(/[TZ:-]/g, '')
+      .replace(/\..*/, '');
+    // url must not be percent-encoded — Wayback Machine matches on the raw URL
+    const captureHref = `https://web.archive.org/web/${captureDateStr}/${url}`;
+    const captureText = formatDate(date, 'long');
+
+    return html` <a href=${captureHref}> ${captureText} </a> `;
+  }
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/tiles/tile-mediatype-icon.ts

@@ -0,0 +1,133 @@
+import { css, CSSResultGroup, html, LitElement } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+import {
+  mediatypeConfig,
+  MediatypeConfigKey,
+} from '../mediatype/mediatype-config';
+import type { TileModel } from '../models';
+
+const TV_COMMERCIAL_COLLECTION = 'tv_ads';
+const TV_FACT_CHECK_COLLECTION = 'factchecked';
+const TV_COLLECTIONS = new Set(['tvnews', 'tvarchive', 'television']);
+const RADIO_COLLECTIONS = new Set(['radio', 'radioprogram']);
+
+@customElement('tile-mediatype-icon')
+export class TileMediatypeIcon extends LitElement {
+  @property({ type: Object }) model?: TileModel;
+
+  @property({ type: Boolean }) showText = false;
+
+  /**
+   * Returns the appropriate mediatype config key for the current mediatype/collections.
+   */
+  private get displayMediatype(): MediatypeConfigKey {
+    if (this.isTvItem) return this.tvDisplayMediatype;
+    if (this.isRadioItem) return 'radio';
+    return this.model?.mediatype ?? 'none';
+  }
+
+  /**
+   * Returns the appropriate TV mediatype, depending on the current collections.
+   */
+  private get tvDisplayMediatype(): MediatypeConfigKey {
+    if (this.isTvCommercial) {
+      return 'tvCommercial';
+    } else if (this.model?.isTvSearchResult && this.isTvFactCheck) {
+      return 'tvFactCheck';
+    } else if (this.model?.isTvSearchResult && this.isTvQuote) {
+      return 'tvQuote';
+    }
+
+    return 'tv';
+  }
+
+  /**
+   * Whether this represents a TV item
+   */
+  private get isTvItem(): boolean {
+    return !!(
+      this.model?.mediatype === 'movies' &&
+      this.model?.collections.some(id => TV_COLLECTIONS.has(id))
+    );
+  }
+
+  private get isTvCommercial(): boolean {
+    // Contains one or more TV ad identifiers or is in the tv_ads collection
+    return !!(
+      this.model?.adIds?.length ||
+      this.model?.collections.includes(TV_COMMERCIAL_COLLECTION)
+    );
+  }
+
+  private get isTvFactCheck(): boolean {
+    // Contains one or more fact-check URLs or is in the factchecked collection
+    return !!(
+      this.model?.factChecks?.length ||
+      this.model?.collections.includes(TV_FACT_CHECK_COLLECTION)
+    );
+  }
+
+  private get isTvQuote(): boolean {
+    return !!this.model?.isClip;
+  }
+
+  /**
+   * Whether this represents a radio item
+   */
+  private get isRadioItem(): boolean {
+    return !!(
+      this.model?.mediatype === 'audio' &&
+      this.model?.collections.some(id => RADIO_COLLECTIONS.has(id))
+    );
+  }
+
+  render() {
+    const config = mediatypeConfig[this.displayMediatype];
+    if (!config) {
+      return html``;
+    }
+
+    return html`
+      <div
+        id="icon"
+        class="${this.showText ? 'show-text' : 'hide-text'}"
+        title="${config.text}"
+        style="--iconFillColor: ${config.color}"
+      >
+        ${config.icon}
+        <p class="status-text">${config.text}</p>
+      </div>
+    `;
+  }
+
+  static get styles(): CSSResultGroup {
+    return css`
+      #icon {
+        height: var(--iconHeight, 25px);
+      }
+
+      .status-text {
+        font-size: 14px;
+        color: #2c2c2c;
+        margin: auto;
+        display: block;
+        text-align: var(--iconTextAlign, center);
+      }
+
+      #icon.hide-text p {
+        display: none;
+      }
+
+      svg {
+        height: var(--iconHeight, 10px);
+        width: var(--iconWidth, 10px);
+        pointer-events: none;
+      }
+
+      .fill-color {
+        fill: var(--iconFillColor, '#000000');
+      }
+    `;
+  }
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/utils/analytics-events.ts

@@ -0,0 +1,29 @@
+/**
+ * Analytics categories and events. Used when building actions in
+ */
+export enum analyticsCategories {
+  default = 'collection-browser',
+}
+
+export enum analyticsActions {
+  sortBy = 'sortBy',
+  filterByCreator = 'filterByCreator',
+  filterByTitle = 'filterByTitle',
+  displayMode = 'displayMode',
+  loadDesktopView = 'loadDesktopView',
+  loadMobileView = 'loadMobileView',
+  facetSelected = 'facetSelected',
+  facetDeselected = 'facetDeselected',
+  facetNegativeSelected = 'facetNegativeSelected',
+  facetNegativeDeselected = 'facetNegativeDeselected',
+  mobileFacetsToggled = 'mobileFacetsToggled',
+  partOfCollectionClicked = 'partOfCollectionClicked',
+  histogramChanged = 'histogramChanged',
+  histogramChangedFromModal = 'histogramChangedFromModal',
+  histogramExpanded = 'histogramExpanded',
+  resultSelected = 'resultSelected',
+  moreFacetsPageChange = 'moreFacetsPageChange',
+  showMoreFacetsModal = 'showMoreFacetsModal',
+  closeMoreFacetsModal = 'closeMoreFacetsModal',
+  applyMoreFacetsModal = 'applyMoreFacetsModal',
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/utils/array-equals.ts

@@ -0,0 +1,8 @@
+/**
+ * Determines whether two arrays have the same (shallow) contents in the same order
+ */
+export function arrayEquals(arr1: unknown[], arr2: unknown[]): boolean {
+  if (arr1 === arr2) return true;
+  if (arr1.length !== arr2.length) return false;
+  return arr1.every((val, i) => val === arr2[i]);
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/utils/collapse-repeated-quotes.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns the input string, but removing one set of quotes from all instances of
+ * ""clauses wrapped in two sets of quotes"". This assumes the quotes are already
+ * URL-encoded.
+ *
+ * This should be a temporary measure to address the fact that the __href__ field
+ * sometimes acquires extra quotation marks during query rewriting. Once there is a
+ * full Lucene parser in place that handles quoted queries correctly, this can likely
+ * be removed.
+ */
+export function collapseRepeatedQuotes(str?: string): string | undefined {
+  return str?.replace(/%22%22(?!%22%22)(.+?)%22%22/g, '%22$1%22');
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/utils/date-filter-field.ts

@@ -0,0 +1,11 @@
+/**
+ * Determines the appropriate search filter field name based on date format.
+ * Dates in YYYY-MM format (containing a hyphen) use the `date` field;
+ * dates in YYYY format use the `year` field.
+ */
+export function dateFilterField(
+  minDate?: string,
+  maxDate?: string,
+): 'date' | 'year' {
+  return minDate?.includes('-') || maxDate?.includes('-') ? 'date' : 'year';
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/utils/facet-utils.ts

@@ -0,0 +1,183 @@
+import { AggregationSortType } from '@internetarchive/search-service';
+import {
+  FacetOption,
+  getDefaultSelectedFacets,
+  type FacetBucket,
+  type SelectedFacets,
+} from '../models';
+
+// This file contains several helper functions designed to make working immutably
+// with SelectedFacet objects and FacetGroups cleaner & easier.
+
+/**
+ * Calls the given function for each FacetBucket specified in the given SelectedFacets
+ * object. The function is always called with the facet type, bucket key, bucket object,
+ * and the given SelectedFacets object.
+ *
+ * @param selectedFacets The SelectedFacets object whose buckets should be iterated over
+ * @param fn The function to apply to each facet bucket.
+ *
+ * @example
+ * forEachFacetBucket(
+ *   myFacets,
+ *   (facetType, bucketKey, bucket) => {
+ *     if (facetType === 'collection' && bucket.state === 'hidden') {
+ *       console.log(`Excluding any results in the ${bucketKey} collection`);
+ *     }
+ *   }
+ * );
+ */
+export function forEachFacetBucket(
+  selectedFacets: SelectedFacets | undefined,
+  fn: (
+    facetType: FacetOption,
+    bucketKey: string,
+    bucket: FacetBucket,
+    selectedFacets: SelectedFacets,
+  ) => unknown,
+): void {
+  if (!selectedFacets) return;
+  for (const [facetType, facetBuckets] of Object.entries(selectedFacets)) {
+    for (const [bucketKey, bucket] of Object.entries(facetBuckets)) {
+      fn(facetType as FacetOption, bucketKey, bucket, selectedFacets);
+    }
+  }
+}
+
+/**
+ * Returns a new SelectedFacets object having only the specified bucket changed to
+ * reflect its new provided value. The bucket key is determined from the provided
+ * `bucket` itself.
+ * @param selectedFacets The SelectedFacets object to produce an updated clone of
+ * @param facetType The type of facet to be modified (e.g., 'mediatype', 'subject', ...)
+ * @param bucket The new bucket that should be present on the result
+ * @param omitNoneState If set to true, the returned object will omit the given
+ * bucket entirely if it is updated to state `'none'`. Default is false, which leaves
+ * the `'none'` state in place.
+ */
+export function updateSelectedFacetBucket(
+  selectedFacets: SelectedFacets | undefined,
+  facetType: FacetOption,
+  bucket: FacetBucket,
+  omitNoneState = false,
+): SelectedFacets {
+  const defaultedSelectedFacets = selectedFacets ?? getDefaultSelectedFacets();
+  const newFacets: SelectedFacets = {
+    ...defaultedSelectedFacets,
+    [facetType]: {
+      ...defaultedSelectedFacets[facetType],
+      [bucket.key]: bucket,
+    },
+  };
+
+  if (omitNoneState && bucket.state === 'none') {
+    delete newFacets[facetType]?.[bucket.key];
+  }
+
+  return newFacets;
+}
+
+/**
+ * Creates a clone of the given SelectedFacets object.
+ *
+ * Note that the underlying FacetBucket objects are not deep-cloned -- they will
+ * be references to the same objects as in the input. However, the objects
+ * containing the FacetBuckets for each FacetOption are created anew.
+ *
+ * If the provided argument is undefined, returns an empty SelectedFacets object.
+ *
+ * @param selectedFacets The SelectedFacets object to be cloned
+ */
+export function cloneSelectedFacets(
+  selectedFacets: SelectedFacets | undefined,
+): SelectedFacets {
+  const cloneResult = getDefaultSelectedFacets();
+  forEachFacetBucket(selectedFacets, (facetType, bucketKey, bucket) => {
+    if (!cloneResult[facetType]) cloneResult[facetType] = {};
+    cloneResult[facetType][bucketKey] = bucket;
+  });
+  return cloneResult;
+}
+
+/**
+ * Creates a new SelectedFacets object representing a merge of the `source` facets object
+ * into the `destination` facets object. Any facets existing in `source` take precedence
+ * over those in `destination` in the event of conflicts.
+ *
+ * The resulting SelectedFacets object is normalized to omit any facet buckets whose
+ * state is `'none'` in the merged result. Consequently, any facets buckets with state
+ * `'none'` in `source` will always be absent from the end result. Likewise, any facet
+ * buckets with state `'none'` in `destination` will be absent _unless_ they are also
+ * present in `source` with a state of `'selected'` or `'hidden'` (in which case `source`
+ * takes precedence as usual).
+ *
+ * @param source The source of the new facets to merge in. Any facet buckets existing in
+ * this `source` object will take precedence over those in `destination` having the same
+ * key, if they exist in both. Any facet buckets that are _not_ present in `source` will
+ * remain unmodified from their state in `destination`, if they are present there at all.
+ * @param destination The destination onto which facets should be merged. Note that this
+ * object is _not_ re-used for the return value, but it is conceptually the "existing base"
+ * onto which the source facets are merged.
+ */
+export function mergeSelectedFacets(
+  destination: SelectedFacets | undefined,
+  source: SelectedFacets | undefined,
+): SelectedFacets {
+  const mergeResult = cloneSelectedFacets(destination);
+  forEachFacetBucket(source, (facetType, bucketKey, bucket) => {
+    if (!mergeResult[facetType]) mergeResult[facetType] = {};
+    mergeResult[facetType][bucketKey] = bucket;
+  });
+
+  // Normalize any 'none' states on the result (from either source or destination)
+  forEachFacetBucket(mergeResult, (facetType, bucketKey, bucket) => {
+    if (bucket.state === 'none') {
+      delete mergeResult[facetType]?.[bucketKey];
+    }
+  });
+
+  return mergeResult;
+}
+
+/**
+ * Defines the order of states in which to display SelectedFacets buckets
+ */
+const BUCKET_STATE_ORDER = ['selected', 'hidden', 'none'];
+
+/**
+ * Sorts the provided FacetBuckets so that:
+ * - Any selected items come first
+ * - Any hidden items come after all the selected items
+ * - Any unselected / unhidden items come last
+ *
+ * Within each of the above groups, the buckets will be sorted according to
+ * the provided sort type, or by their bucket count by default.
+ *
+ * The sort is performed in-place using `Array.sort`, so the return value is
+ * a reference to the same array that was passed in, only sorted.
+ *
+ * @param buckets The array of facet buckets to sort
+ * @param sort (Optional) How buckets within each state group should be sorted.
+ * Defaults to `AggregationSortType.COUNT` (i.e., descending by bucket count).
+ */
+export function sortBucketsBySelectionState(
+  buckets: FacetBucket[],
+  sort = AggregationSortType.COUNT,
+) {
+  return buckets.sort((a, b) => {
+    const aStateIndex = BUCKET_STATE_ORDER.indexOf(a.state);
+    const bStateIndex = BUCKET_STATE_ORDER.indexOf(b.state);
+    const stateDiff = aStateIndex - bStateIndex; // Sort bucket states primarily in the order defined by BUCKET_STATE_ORDER
+
+    let secondaryDiff;
+    if (sort === AggregationSortType.ALPHABETICAL) {
+      secondaryDiff = a.key.localeCompare(b.key); // Ascending alphabetically by bucket key
+    } else if (sort === AggregationSortType.NUMERIC) {
+      secondaryDiff = Number(b.key) - Number(a.key); // Descending numerically by bucket key
+    } else {
+      secondaryDiff = b.count - a.count; // Descending by bucket count
+    }
+
+    return stateDiff || secondaryDiff; // Primary sort on state, secondary sort on the given sort type (defaulting to descending count)
+  });
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/utils/format-count.ts

@@ -0,0 +1,95 @@
+/*
+ * Replaces Petabox www/common/Util::number_format()
+ * For positive numbers only.
+ */
+import { msg, str } from '@lit/localize';
+
+export type NumberFormat =
+  | 'short' // 1.2 [K | thousand]
+  | 'long'; // 1,200 [No label for numbers < 1,000,000]
+export type LabelFormat =
+  | 'short' // [1.2]K
+  | 'long'; // [1.2] thousand
+type Divisor = 1_000_000_000 | 1_000_000 | 1_000 | 1;
+
+/**
+ * Return the magnitude of a number.
+ */
+function magnitude(number: number, numberFormat: NumberFormat): Divisor {
+  let divisor: Divisor = 1;
+  if (number >= 1_000_000_000) {
+    divisor = 1_000_000_000;
+  } else if (number >= 1_000_000) {
+    divisor = 1_000_000;
+  } else if (number >= 1_000 && numberFormat === 'short') {
+    divisor = 1_000;
+  }
+  return divisor;
+}
+
+/**
+ * Round a number given passed magnitude.
+ * Significant digits of value less than 10 get a decimal.
+ */
+function round(number: number = 0, divisor: Divisor): number {
+  const result = number / divisor;
+  const roundToOne = result < 10;
+  let rounded: number = 0;
+  if (roundToOne) {
+    rounded = Math.round((result + Number.EPSILON) * 10) / 10;
+  } else {
+    rounded = Math.round(result);
+  }
+  return rounded;
+}
+
+/**
+ * Return a label for a number and format.
+ */
+function labelize(
+  rounded: number,
+  divisor: Divisor,
+  format: LabelFormat,
+  locale: string,
+): string {
+  switch (divisor) {
+    case 1_000_000_000:
+      if (format === 'short') {
+        return msg(str`${rounded}B`);
+      }
+      return msg(str`${rounded} billion`);
+    case 1_000_000:
+      if (format === 'short') {
+        return msg(str`${rounded}M`);
+      }
+      return msg(str`${rounded} million`);
+    case 1_000:
+      if (format === 'short') {
+        return msg(str`${rounded}K`);
+      }
+      return msg(str`${rounded} thousand`);
+
+    default:
+      return new Intl.NumberFormat(locale).format(rounded);
+  }
+}
+
+/**
+ * Format a "count" number into short "icon" or longer text string.
+ * For positive numbers only.
+ */
+export function formatCount(
+  count: number | undefined,
+  numberFormat: NumberFormat = 'long',
+  labelFormat: LabelFormat = 'short',
+  locale: string = 'en-US',
+): string {
+  // Return blank if undefined
+  const number = count ?? -1;
+  if (number < 0) {
+    return '';
+  }
+  const divisor = magnitude(number, numberFormat);
+  const rounded = round(number, divisor);
+  return labelize(rounded, divisor, labelFormat, locale);
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/utils/format-date.ts

@@ -0,0 +1,62 @@
+/*
+ * Display date
+ * Override browser timezone to always display same date as in data
+ */
+export type DateFormat =
+  | 'year-only' // 2020
+  | 'short' // Dec 2020
+  | 'long'; // Dec 20, 2020
+
+/**
+ * Extra options accepted by the `formatDate` function
+ */
+export type FormatDateOptions = {
+  /**
+   * Which locale to format the date string for (default `'en-US'`)
+   */
+  locale?: string;
+  /**
+   * Whether to display the date in the browser's local time zone.
+   * Default is `false`, displaying the dates in UTC.
+   */
+  useLocalTime?: boolean;
+};
+
+export function formatDate(
+  date: Date | undefined,
+  format: DateFormat = 'short',
+  { locale = 'en-US', useLocalTime = false }: FormatDateOptions = {},
+): string {
+  // Return blank if undefined
+  if (!date) return '';
+
+  // The dates provided by the backend are assumed to already be with respect to UTC,
+  // and by default we specify that they should be rendered as such. If the
+  // `useLocalTime` option was set, we omit the UTC time zone from our format options
+  // so that the browser's local time zone is used instead.
+  const options: Intl.DateTimeFormatOptions = useLocalTime
+    ? {}
+    : { timeZone: 'UTC' };
+
+  switch (format) {
+    case 'year-only':
+      // If we're only using the year, ensure we output the correct UTC year and not
+      // the local year. If the local timezone is used, we can get strange off-by-one
+      // errors due to quirks of timezone handling for older years.
+      return `${date.getUTCFullYear()}`;
+    case 'short':
+      options.month = 'short';
+      options.year = 'numeric';
+      break;
+    case 'long':
+      options.year = 'numeric';
+      options.month = 'short';
+      options.day = '2-digit';
+      break;
+    default:
+      break;
+  }
+
+  const dateFormatter = new Intl.DateTimeFormat(locale, options);
+  return dateFormatter.format(date);
+}