@internetarchive/collection-browser 1.8.0 → 1.9.0-alpha1

package/src/models.ts

@@ -56,6 +56,7 @@ export type CollectionBrowserContext = 'collection' | 'search';
  */
 export enum SortField {
   'default' = 'default',
+  'unrecognized' = 'unrecognized',
   'relevance' = 'relevance',
   'alltimeview' = 'alltimeview',
   'weeklyview' = 'weeklyview',
@@ -67,120 +68,203 @@ export enum SortField {
   'creator' = 'creator',
 }
 
-/**
- * The metadata fields we sort by that map to the SortFields above
- */
-export type MetadataSortField =
-  | 'downloads'
-  | 'week'
-  | 'titleSorter'
-  | 'date'
-  | 'creatorSorter'
-  | 'publicdate'
-  | 'reviewdate'
-  | 'addeddate';
-
-/**
- * All sort strings recognized in search URLs
- */
-export type URLSortField = MetadataSortField | 'title' | 'creator';
-
-export const SortFieldDisplayName: {
-  [key in SortField]: string;
-} = {
-  default: '', // Use the default sorting option for the current page context, if none has been selected
-  relevance: 'Relevance',
-  alltimeview: 'All-time views',
-  weeklyview: 'Weekly views',
-  title: 'Title',
-  date: 'Date published',
-  datearchived: 'Date archived',
-  datereviewed: 'Date reviewed',
-  dateadded: 'Date added',
-  creator: 'Creator',
-};
-
-export const DefaultSortDirection: {
-  [key in SortField]: SortDirection | null;
-} = {
-  default: null,
-  relevance: null, // Sort direction is disabled entirely for relevance sort (user can't click the button)
-  alltimeview: 'desc',
-  weeklyview: 'desc',
-  title: 'asc',
-  date: 'desc',
-  datearchived: 'desc',
-  datereviewed: 'desc',
-  dateadded: 'desc',
-  creator: 'asc',
-};
-
-/**
- * Maps the SortField above to the corresponding Metadata field in the API.
- */
-export const SortFieldToMetadataField: {
-  [key in SortField]: MetadataSortField | null;
-} = {
-  default: null,
-  relevance: null,
-  alltimeview: 'downloads',
-  weeklyview: 'week',
-  title: 'titleSorter',
-  date: 'date',
-  datearchived: 'publicdate',
-  datereviewed: 'reviewdate',
-  dateadded: 'addeddate',
-  creator: 'creatorSorter',
-};
-
-/**
- * Maps the Metadata field to the corresponding SortField field in the API.
- */
-export const MetadataFieldToSortField: {
-  [key in MetadataSortField]: SortField;
-} = {
-  week: SortField.weeklyview,
-  downloads: SortField.alltimeview,
-  titleSorter: SortField.title,
-  date: SortField.date,
-  publicdate: SortField.datearchived,
-  reviewdate: SortField.datereviewed,
-  addeddate: SortField.dateadded,
-  creatorSorter: SortField.creator,
-};
+export interface SortOption {
+  /**
+   * The SortField enum member corresponding to this option.
+   */
+  field: SortField;
+
+  /**
+   * The default sort direction to apply when this sort option is first selected.
+   */
+  defaultSortDirection: SortDirection | null;
+
+  /**
+   * Whether this sort option allows its sort direction to be changed from the default.
+   */
+  canSetDirection: boolean;
+
+  /**
+   * Whether this sort option may appear in the sort bar.
+   */
+  shownInSortBar: boolean;
+
+  /**
+   * Whether this sort option should be saved to the URL.
+   * If false, then no `sort` param will be added to the URL when this sort option
+   * is selected.
+   */
+  shownInURL: boolean;
+
+  /**
+   * Whether this sort option is passed to the search service.
+   * If false, then no sort param will be passed to the search service at all when
+   * this sort option is selected.
+   */
+  handledBySearchService: boolean;
+
+  /**
+   * The string identifying this sort field to the search service & backend API.
+   */
+  searchServiceKey?: string;
+
+  /**
+   * The human-readable name to use for this option in the sort bar (if applicable).
+   */
+  displayName: string;
+
+  /**
+   * A list of URL param keys that should be mapped to this sort option.
+   * E.g., both `title` and `titleSorter` in the URL map to the `SortField.title` option.
+   */
+  urlNames: (string | null | undefined)[];
+}
 
-/**
- * Maps the Metadata fields to how they should be presented in URLs.
- */
-export const MetadataFieldToURLField: {
-  [key in MetadataSortField]: URLSortField;
-} = {
-  week: 'week',
-  downloads: 'downloads',
-  titleSorter: 'title',
-  date: 'date',
-  publicdate: 'publicdate',
-  reviewdate: 'reviewdate',
-  addeddate: 'addeddate',
-  creatorSorter: 'creator',
+export const SORT_OPTIONS: Record<SortField, SortOption> = {
+  // Default sort is the case where the user has not specified a sort option via the sort bar or URL.
+  // In these cases, we defer to whatever sort the backend chooses.
+  // For the search page, the default is always relevance sort.
+  // For collection pages _without a query_, the default is usually weekly views, but this can be
+  // overridden by the collection's `sort-by` metadata entry. If a query _is_ specified, then the
+  // default is again relevance sort.
+  [SortField.default]: {
+    field: SortField.default,
+    defaultSortDirection: null,
+    canSetDirection: false,
+    shownInSortBar: false,
+    shownInURL: false,
+    handledBySearchService: false, // We rely on the PPS default sort handling in these cases
+    displayName: '',
+    urlNames: ['', null, undefined], // Empty or nullish sort params result in default sorting
+  },
+  // Unrecognized sort is the case where the user has specified a sort in the URL, but it is not
+  // one of the options listed in this map. We still want these unrecognized sorts to be applied
+  // when searching, but they are not displayed in the sort bar and we do not actively manage
+  // their URL param beyond flipping the direction as needed.
+  [SortField.unrecognized]: {
+    field: SortField.unrecognized,
+    defaultSortDirection: null,
+    canSetDirection: true,
+    shownInSortBar: false,
+    shownInURL: false,
+    handledBySearchService: true, // The unrecognized sort param is passed along as-is
+    displayName: '',
+    urlNames: [],
+  },
+  // Relevance sort is unique in that it does not produce a URL param when it is set.
+  // It is only available when there is a user-specified query that relevancy can be scored against.
+  // Therefore, it does not appear as a sort bar option when browsing a collection with no query set.
+  [SortField.relevance]: {
+    field: SortField.relevance,
+    defaultSortDirection: null,
+    canSetDirection: false,
+    shownInSortBar: true,
+    shownInURL: false,
+    handledBySearchService: false,
+    displayName: 'Relevance',
+    urlNames: ['_score'],
+  },
+  [SortField.alltimeview]: {
+    field: SortField.alltimeview,
+    defaultSortDirection: 'desc',
+    canSetDirection: true,
+    shownInSortBar: true,
+    shownInURL: true,
+    handledBySearchService: true,
+    searchServiceKey: 'downloads',
+    displayName: 'All-time views',
+    urlNames: ['downloads'],
+  },
+  [SortField.weeklyview]: {
+    field: SortField.weeklyview,
+    defaultSortDirection: 'desc',
+    canSetDirection: true,
+    shownInSortBar: true,
+    shownInURL: true,
+    handledBySearchService: true,
+    searchServiceKey: 'week',
+    displayName: 'Weekly views',
+    urlNames: ['week'],
+  },
+  [SortField.title]: {
+    field: SortField.title,
+    defaultSortDirection: 'asc',
+    canSetDirection: true,
+    shownInSortBar: true,
+    shownInURL: true,
+    handledBySearchService: true,
+    searchServiceKey: 'titleSorter',
+    displayName: 'Title',
+    urlNames: ['title', 'titleSorter'],
+  },
+  [SortField.date]: {
+    field: SortField.date,
+    defaultSortDirection: 'desc',
+    canSetDirection: true,
+    shownInSortBar: true,
+    shownInURL: true,
+    handledBySearchService: true,
+    searchServiceKey: 'date',
+    displayName: 'Date published',
+    urlNames: ['date'],
+  },
+  [SortField.datearchived]: {
+    field: SortField.datearchived,
+    defaultSortDirection: 'desc',
+    canSetDirection: true,
+    shownInSortBar: true,
+    shownInURL: true,
+    handledBySearchService: true,
+    searchServiceKey: 'publicdate',
+    displayName: 'Date archived',
+    urlNames: ['publicdate'],
+  },
+  [SortField.datereviewed]: {
+    field: SortField.datereviewed,
+    defaultSortDirection: 'desc',
+    canSetDirection: true,
+    shownInSortBar: true,
+    shownInURL: true,
+    handledBySearchService: true,
+    searchServiceKey: 'reviewdate',
+    displayName: 'Date reviewed',
+    urlNames: ['reviewdate'],
+  },
+  [SortField.dateadded]: {
+    field: SortField.dateadded,
+    defaultSortDirection: 'desc',
+    canSetDirection: true,
+    shownInSortBar: true,
+    shownInURL: true,
+    handledBySearchService: true,
+    searchServiceKey: 'addeddate',
+    displayName: 'Date added',
+    urlNames: ['addeddate'],
+  },
+  [SortField.creator]: {
+    field: SortField.creator,
+    defaultSortDirection: 'asc',
+    canSetDirection: true,
+    shownInSortBar: true,
+    shownInURL: true,
+    handledBySearchService: true,
+    searchServiceKey: 'creatorSorter',
+    displayName: 'Creator',
+    urlNames: ['creator', 'creatorSorter'],
+  },
 };
 
 /**
- * Maps all allowable sort strings from the URL to their respective
- * sort fields.
+ * Returns the SortOption corresponding to the given API sort name, or
+ * the "unrecognized" SortOption if none matches.
  */
-export const URLFieldToSortField: Record<URLSortField, SortField> = {
-  week: SortField.weeklyview,
-  downloads: SortField.alltimeview,
-  title: SortField.title,
-  titleSorter: SortField.title,
-  date: SortField.date,
-  publicdate: SortField.datearchived,
-  reviewdate: SortField.datereviewed,
-  addeddate: SortField.dateadded,
-  creator: SortField.creator,
-  creatorSorter: SortField.creator,
-};
+export function sortOptionFromAPIString(sortName?: string | null): SortOption {
+  return (
+    Object.values(SORT_OPTIONS).find(opt =>
+      opt.urlNames.some(name => sortName === name)
+    ) ?? SORT_OPTIONS[SortField.unrecognized]
+  );
+}
 
 /** A union of the fields that permit prefix filtering (e.g., alphabetical filtering) */
 export type PrefixFilterType = 'title' | 'creator';

package/src/restoration-state-handler.ts

@@ -1,11 +1,6 @@
-import {
-  SearchType,
-  SortDirection,
-  SortParam,
-} from '@internetarchive/search-service';
+import { SearchType, SortDirection } from '@internetarchive/search-service';
 import { getCookie, setCookie } from 'typescript-cookie';
 import {
-  MetadataSortField,
   FacetOption,
   CollectionBrowserContext,
   CollectionDisplayMode,
@@ -13,17 +8,15 @@ import {
   SortField,
   FacetBucket,
   FacetState,
-  URLFieldToSortField,
-  URLSortField,
   getDefaultSelectedFacets,
-  MetadataFieldToURLField,
+  sortOptionFromAPIString,
+  SORT_OPTIONS,
 } from './models';
 import { arrayEquals } from './utils/array-equals';
 
 export interface RestorationState {
   displayMode?: CollectionDisplayMode;
   searchType?: SearchType;
-  sortParam?: SortParam;
   selectedSort?: SortField;
   sortDirection?: SortDirection;
   selectedFacets: SelectedFacets;
@@ -120,11 +113,29 @@ export class RestorationStateHandler
       }
     }
 
-    if (state.sortParam) {
-      const prefix = state.sortParam.direction === 'desc' ? '-' : '';
-      const readableSortField =
-        MetadataFieldToURLField[state.sortParam.field as MetadataSortField];
-      newParams.set('sort', `${prefix}${readableSortField}`);
+    if (state.selectedSort) {
+      const sortOption = SORT_OPTIONS[state.selectedSort];
+      let prefix = this.sortDirectionPrefix(state.sortDirection);
+
+      if (sortOption.field === SortField.unrecognized) {
+        // For unrecognized sorts, use the existing param, possibly updating its direction
+        const oldSortParam = oldParams.get('sort') ?? '';
+        const { field, direction } =
+          this.getSortFieldAndDirection(oldSortParam);
+
+        // Use the state-specified direction if available, or extract one from the param if not
+        if (!state.sortDirection) prefix = this.sortDirectionPrefix(direction);
+
+        if (field) {
+          newParams.set('sort', `${prefix}${field}`);
+        } else {
+          newParams.set('sort', oldSortParam);
+        }
+      } else if (sortOption.shownInURL) {
+        // Otherwise, use the canonical API form of the sort option
+        const canonicalApiSort = sortOption.urlNames[0];
+        newParams.set('sort', `${prefix}${canonicalApiSort}`);
+      }
     }
 
     if (state.selectedFacets) {
@@ -197,7 +208,7 @@ export class RestorationStateHandler
         query: state.baseQuery,
         searchType: state.searchType,
         page: state.currentPage,
-        sort: state.sortParam,
+        sort: { field: state.selectedSort, direction: state.sortDirection },
         minDate: state.minSelectedDate,
         maxDate: state.maxSelectedDate,
         facets: state.selectedFacets,
@@ -261,29 +272,13 @@ export class RestorationStateHandler
     }
 
     if (sortQuery) {
-      // check for two different sort formats: `date desc` and `-date`
-      const hasSpace = sortQuery.indexOf(' ') > -1;
-      if (hasSpace) {
-        const [field, direction] = sortQuery.split(' ');
-        const metadataField = URLFieldToSortField[field as URLSortField];
-
-        if (metadataField) {
-          restorationState.selectedSort = metadataField;
-        }
-        if (direction === 'desc' || direction === 'asc') {
-          restorationState.sortDirection = direction as SortDirection;
-        }
-      } else {
-        const direction = sortQuery.startsWith('-') ? 'desc' : 'asc';
-        const field = sortQuery.startsWith('-')
-          ? sortQuery.slice(1)
-          : sortQuery;
-
-        const metadataField = URLFieldToSortField[field as URLSortField];
-        if (metadataField) {
-          restorationState.selectedSort = metadataField;
-          restorationState.sortDirection = direction as SortDirection;
-        }
+      const { field, direction } = this.getSortFieldAndDirection(sortQuery);
+
+      const sortOption = sortOptionFromAPIString(field);
+      restorationState.selectedSort = sortOption.field;
+
+      if (['asc', 'desc'].includes(direction)) {
+        restorationState.sortDirection = direction as SortDirection;
       }
     }
 
@@ -296,6 +291,13 @@ export class RestorationStateHandler
         // which we want to normalize to 'creator', 'language', etc. if redirected here.
         field = field.replace(/Sorter$/, '');
 
+        // Legacy search also allowed a form of negative faceting like `and[]=-collection:foo`
+        // which we want to normalize to a not[] param instead
+        if (field.startsWith('-')) {
+          facetNots.push(and.slice(1));
+          return;
+        }
+
         switch (field) {
           case 'year': {
             const [minDate, maxDate] = value.split(' TO ');
@@ -354,7 +356,31 @@ export class RestorationStateHandler
     return restorationState;
   }
 
-  // remove optional opening and closing quotes from a string
+  /**
+   * Converts a URL sort param into a field/direction pair, if possible.
+   * Either or both may be undefined if the param is not in a recognized format.
+   */
+  private getSortFieldAndDirection(sortParam: string) {
+    // check for two different sort formats: `date desc` and `-date`
+    const hasSpace = sortParam.indexOf(' ') > -1;
+    let field;
+    let direction;
+    if (hasSpace) {
+      [field, direction] = sortParam.split(' ');
+    } else {
+      field = sortParam.startsWith('-') ? sortParam.slice(1) : sortParam;
+      direction = sortParam.startsWith('-') ? 'desc' : 'asc';
+    }
+
+    return { field, direction };
+  }
+
+  /** Returns the `-` prefix for `desc` sort, or the empty string otherwise. */
+  private sortDirectionPrefix(sortDirection?: string) {
+    return sortDirection === 'desc' ? '-' : '';
+  }
+
+  /** Remove optional opening and closing quotes from a string */
   private stripQuotes(value: string): string {
     if (value.startsWith('"') && value.endsWith('"')) {
       return value.substring(1, value.length - 1);

package/src/sort-filter-bar/sort-filter-bar.ts

@@ -16,11 +16,10 @@ import type { IaDropdown, optionInterface } from '@internetarchive/ia-dropdown';
 import type { SortDirection } from '@internetarchive/search-service';
 import {
   CollectionDisplayMode,
-  DefaultSortDirection,
   PrefixFilterCounts,
   PrefixFilterType,
+  SORT_OPTIONS,
   SortField,
-  SortFieldDisplayName,
 } from '../models';
 import './alpha-bar';
 
@@ -153,7 +152,8 @@ export class SortFilterBar
     }
 
     if (changed.has('selectedSort') && this.sortDirection === null) {
-      this.sortDirection = DefaultSortDirection[this.finalizedSortField];
+      const sortOption = SORT_OPTIONS[this.finalizedSortField];
+      this.sortDirection = sortOption.defaultSortDirection;
     }
 
     if (changed.has('selectedTitleFilter') && this.selectedTitleFilter) {
@@ -274,7 +274,7 @@ export class SortFilterBar
     return html`
       <button
         class="sort-direction-selector"
-        ?disabled=${this.finalizedSortField === SortField.relevance}
+        ?disabled=${!this.canChangeSortDirection}
         @click=${this.handleSortDirectionClicked}
       >
         <span class="sr-only">${srLabel}</span>
@@ -285,8 +285,8 @@ export class SortFilterBar
 
   /** Template to render the sort direction button's icon in the correct current state */
   private get sortDirectionIcon(): TemplateResult {
-    // For relevance sort, show a fully disabled icon
-    if (this.finalizedSortField === SortField.relevance) {
+    // Show a fully disabled icon for sort options without direction support
+    if (!this.canChangeSortDirection) {
       return html`<div class="sort-direction-icon">${sortDisabledIcon}</div>`;
     }
 
@@ -354,9 +354,9 @@ export class SortFilterBar
 
   /** The template to render all the sort options in mobile view */
   private get mobileSortSelectorTemplate() {
-    const isDisplayableField = (field: string) =>
-      field !== SortField.default &&
-      (field !== SortField.relevance || this.showRelevance);
+    const displayedOptions = Object.values(SORT_OPTIONS)
+      .filter(opt => opt.shownInSortBar)
+      .filter(opt => this.showRelevance || opt.field !== SortField.relevance);
 
     return html`
       <div
@@ -364,13 +364,13 @@ export class SortFilterBar
         class=${this.mobileSelectorVisible ? 'visible' : 'hidden'}
       >
         ${this.getSortDropdown({
-          displayName: html`${SortFieldDisplayName[this.finalizedSortField] ??
-          'Relevance'}`,
+          displayName: html`${SORT_OPTIONS[this.finalizedSortField]
+            .displayName}`,
           id: 'mobile-dropdown',
           selected: true,
-          dropdownOptions: Object.keys(SortField)
-            .filter(field => isDisplayableField(field))
-            .map(field => this.getDropdownOption(field as SortField)),
+          dropdownOptions: displayedOptions.map(opt =>
+            this.getDropdownOption(opt.field)
+          ),
           selectedOption: this.finalizedSortField,
           onOptionSelected: this.mobileSortChanged,
           onDropdownClick: () => {
@@ -408,7 +408,8 @@ export class SortFilterBar
   ): TemplateResult {
     const isSelected =
       options?.selected ?? this.finalizedSortField === sortField;
-    const displayName = options?.displayName ?? SortFieldDisplayName[sortField];
+    const displayName =
+      options?.displayName ?? SORT_OPTIONS[sortField].displayName;
     return html`
       <button
         class=${isSelected ? 'selected' : nothing}
@@ -488,7 +489,7 @@ export class SortFilterBar
       },
       label: html`
         <span class="dropdown-option-label">
-          ${SortFieldDisplayName[sortField]}
+          ${SORT_OPTIONS[sortField].displayName}
         </span>
       `,
     };
@@ -692,7 +693,8 @@ export class SortFilterBar
   private setSelectedSort(sort: SortField) {
     this.selectedSort = sort;
     // Apply this field's default sort direction
-    this.sortDirection = DefaultSortDirection[this.selectedSort];
+    const sortOption = SORT_OPTIONS[sort];
+    this.sortDirection = sortOption.defaultSortDirection;
     this.emitSortChangedEvent();
   }
 
@@ -710,6 +712,11 @@ export class SortFilterBar
       : this.sortDirection;
   }
 
+  /** Whether the sort direction button should be enabled for the current sort */
+  private get canChangeSortDirection(): boolean {
+    return SORT_OPTIONS[this.finalizedSortField].canSetDirection;
+  }
+
   /**
    * There are four date sort options.
    *
@@ -757,11 +764,11 @@ export class SortFilterBar
    * @memberof SortFilterBar
    */
   private get dateSortField(): string {
-    const defaultSort = SortFieldDisplayName[SortField.date];
-    const name = this.dateOptionSelected
-      ? SortFieldDisplayName[this.finalizedSortField] ?? defaultSort
-      : defaultSort;
-    return name;
+    const defaultDateSort = SORT_OPTIONS[SortField.date];
+    const currentDateSort = this.dateOptionSelected
+      ? SORT_OPTIONS[this.finalizedSortField] ?? defaultDateSort
+      : defaultDateSort;
+    return currentDateSort.displayName;
   }
 
   /**
@@ -773,11 +780,11 @@ export class SortFilterBar
    * @memberof SortFilterBar
    */
   private get viewSortField(): string {
-    const defaultSort = SortFieldDisplayName[SortField.weeklyview];
-    const name = this.viewOptionSelected
-      ? SortFieldDisplayName[this.finalizedSortField] ?? defaultSort
-      : defaultSort;
-    return name;
+    const defaultViewSort = SORT_OPTIONS[SortField.weeklyview];
+    const currentViewSort = this.viewOptionSelected
+      ? SORT_OPTIONS[this.finalizedSortField] ?? defaultViewSort
+      : defaultViewSort;
+    return currentViewSort.displayName;
   }
 
   private get titleSelectorBar() {