@internetarchive/collection-browser 4.5.1 → 4.6.0

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/collection-facets/more-facets-pagination.ts

@@ -0,0 +1,294 @@
+import {
+  css,
+  CSSResultGroup,
+  html,
+  LitElement,
+  nothing,
+  TemplateResult,
+} from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import arrowLeftIcon from '../assets/img/icons/arrow-left';
+import arrowRightIcon from '../assets/img/icons/arrow-right';
+import { srOnlyStyle } from '../styles/sr-only';
+
+@customElement('more-facets-pagination')
+export class MoreFacetsPagination extends LitElement {
+  /**
+   * Total number of pages
+   */
+  @property({ type: Number }) size!: number;
+
+  /**
+   * Number of pages can be moved in back/forward
+   */
+  @property({ type: Number }) step = 2;
+
+  @property({ type: Number }) currentPage: number = 1;
+
+  @state() pages?: number[] = [];
+
+  firstUpdated() {
+    this.observePageCount();
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  override updated(changed: Map<string, any>) {
+    if (changed.has('size')) {
+      this.observePageCount();
+    }
+    if (changed.has('currentPage')) {
+      this.observePageCount();
+      this.emitPageClick();
+    }
+  }
+
+  /** creates `this.pages` array that notes which pages to draw
+   * - `0` is elipses marker
+   * - rule: selected page is centered between -2/+2 pages
+   * - outlier: first page selected, show _1_ 2 3 ... N
+   * - outlier: second page selected, show 1 _2_ 3 4 ... N
+   * - outlier: last page selected, show 1 ... N-2 N-1 _N_
+   * - outlier: if page count = 7, & selected is either [2, 3, 4, 5, 6], show all pages
+   */
+  observePageCount() {
+    this.pages = []; /* `0` is elipses marker */
+
+    const paginatorMaxPagesToShow = 7;
+    const atMinThreshold = this.size <= paginatorMaxPagesToShow;
+
+    /** Display outliers  */
+    if (this.size <= 5) {
+      // display all pages
+      this.pages = [...Array(this.size).keys()].map(i => i + 1);
+      return;
+    }
+
+    if (this.size === paginatorMaxPagesToShow) {
+      // edge: 7 pages
+      if (this.currentPage === 2) {
+        this.pages = [1, 2, 3, 4, 0, this.size];
+        return;
+      }
+
+      if (this.currentPage === this.size - 1) {
+        this.pages = [1, 0, 4, 5, this.size - 1, this.size];
+        return;
+      }
+    }
+
+    if (this.currentPage === 1) {
+      // first page
+      this.pages = [1, 2, 3, 0, this.size];
+      return;
+    }
+
+    if (this.currentPage === this.size) {
+      // last page
+      this.pages = [1, 0, this.size - 2, this.size - 1, this.size];
+      return;
+    }
+
+    if (this.currentPage === this.size - 1) {
+      // second last page
+      this.pages = [
+        1,
+        0,
+        this.size - 3,
+        this.size - 2,
+        this.size - 1,
+        this.size,
+      ];
+      return;
+    }
+
+    if (
+      atMinThreshold &&
+      this.currentPage > 1 &&
+      this.currentPage < paginatorMaxPagesToShow
+    ) {
+      this.pages = [...Array(this.size).keys()].map(i => i + 1);
+      return;
+    }
+
+    /* The rest here calculates the range to display in "page window" */
+    let startPage = this.currentPage - this.step;
+    let endPage = this.currentPage + this.step;
+
+    if (startPage <= 0) {
+      endPage += -startPage + 1;
+      startPage = 1;
+    }
+
+    if (endPage >= this.size) {
+      startPage = Math.max(startPage - (endPage - this.size), 1);
+      endPage = this.size;
+    }
+
+    if (startPage === 2) {
+      endPage -= 1;
+    }
+
+    if (endPage === this.size - 1) {
+      startPage += 1;
+    }
+
+    // create first page node
+    this.createFirstNode(startPage);
+
+    // create middle pages node
+    this.createMiddelNode(startPage, endPage);
+
+    // create last page node
+    this.createLastNode(endPage);
+  }
+
+  private createFirstNode(startPage: number) {
+    if (startPage > 1) {
+      this.pages?.push(1);
+    }
+    if (startPage > 2) {
+      this.pages?.push(0); // let's asssume 0 is for ellipsis template
+    }
+  }
+
+  private createMiddelNode(startPage: number, endPage: number) {
+    for (let page = startPage; page <= endPage; page += 1) {
+      this.pages?.push(page);
+    }
+  }
+
+  private createLastNode(endPage: number) {
+    if (endPage < this.size - 1) {
+      this.pages?.push(0); // let's asssume 0 is for ellipsis template
+    }
+    if (endPage < this.size) {
+      this.pages?.push(this.size);
+    }
+  }
+
+  private get getEllipsisTemplate() {
+    return html`<i class="ellipses">...</i>`;
+  }
+
+  emitPageClick() {
+    this.dispatchEvent(
+      new CustomEvent('pageNumberClicked', {
+        detail: { page: this.currentPage },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  private onRewind() {
+    this.currentPage -= 1;
+    if (this.currentPage < 1) {
+      this.currentPage = 1;
+    }
+  }
+
+  private onForward() {
+    this.currentPage += 1;
+    if (this.currentPage > this.size) {
+      this.currentPage = this.size;
+    }
+  }
+
+  private onChange(page: number) {
+    this.currentPage = page;
+  }
+
+  private getPageTemplate(page: number) {
+    return html`
+      <button
+        @click=${() => this.onChange(page)}
+        class=${this.currentPage === page ? 'current' : ''}
+        data-page=${page}
+      >
+        ${page}
+      </button>
+    `;
+  }
+
+  private get getPagesTemplate(): TemplateResult | typeof nothing {
+    if (!this.pages || !this.pages.length) {
+      return nothing;
+    }
+
+    return html`
+      ${this.pages?.map(
+        page =>
+          html`${page !== 0
+            ? this.getPageTemplate(page)
+            : this.getEllipsisTemplate}`,
+      )}
+    `;
+  }
+
+  render() {
+    return html`
+      <div class="facets-pagination">
+        <button class="arrow-icon rewind" @click=${this.onRewind}>
+          <span class="sr-only">Rewind pagination:</span>
+          ${arrowLeftIcon}
+        </button>
+        <div class="page-numbers">${this.getPagesTemplate}</div>
+        <button class="arrow-icon forward" @click=${this.onForward}>
+          <span class="sr-only">Forward pagination:</span>
+          ${arrowRightIcon}
+        </button>
+      </div>
+    `;
+  }
+
+  static get styles(): CSSResultGroup {
+    return [
+      srOnlyStyle,
+      css`
+        .facets-pagination {
+          user-select: none;
+          margin-top: 10px;
+          background-color: #eee;
+          text-align: center;
+        }
+        .facets-pagination button {
+          border: none;
+          background: none;
+        }
+        .facets-pagination .arrow-icon {
+          width: 2.5rem;
+          vertical-align: middle;
+        }
+        .facets-pagination .arrow-icon svg {
+          height: 14px;
+          fill: #2c2c2c;
+        }
+        .facets-pagination button,
+        .facets-pagination i {
+          background: none;
+          border: 0;
+          cursor: pointer;
+          border-radius: 4px;
+          margin: 10px 5px;
+          padding: 5px;
+          font-size: 1.4rem;
+          color: inherit;
+          vertical-align: baseline;
+          display: inline-block;
+          min-width: 2.5rem;
+        }
+        .facets-pagination i {
+          cursor: auto;
+          display: inline;
+        }
+        .facets-pagination button.current {
+          background: #2c2c2c;
+          color: white;
+        }
+        .page-numbers {
+          display: inline-block;
+        }
+      `,
+    ];
+  }
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/collection-facets/smart-facets/dedupe.ts

@@ -0,0 +1,44 @@
+import type { SmartFacet } from './models';
+import { smartFacetEquals } from './smart-facet-equals';
+
+/**
+ * Removes any duplicated smart facets from the given array.
+ * Smart facets are equal if they have the same `label` and same
+ * set of facet refs. Only the first occurrence of a given smart
+ * facet is kept.
+ * @param facets The array of smart facets to deduplicate
+ * @returns A new array containing the deduplicated set of facets
+ */
+export function dedupe<T extends SmartFacet[] | SmartFacet[][]>(facets: T): T {
+  if (!Array.isArray(facets[0])) {
+    const facetsUnnested = facets as SmartFacet[];
+
+    let result: SmartFacet[] = [...facetsUnnested];
+    for (let i = 0; i < result.length; i++) {
+      const curFacet = result[i];
+      result = result.filter(
+        sf => curFacet === sf || !smartFacetEquals(curFacet, sf),
+      );
+    }
+
+    return result as T;
+  }
+
+  const facetsNested = facets as SmartFacet[][];
+
+  const result: SmartFacet[][] = [];
+  for (const curFacetArray of facetsNested) {
+    const subresult: SmartFacet[] = [];
+    for (const curFacet of curFacetArray) {
+      const existing = result.find(sfa =>
+        sfa.find(sf => smartFacetEquals(curFacet, sf)),
+      );
+      if (!existing) subresult.push(curFacet);
+    }
+    if (subresult.length > 0) {
+      result.push(subresult);
+    }
+  }
+
+  return result as T;
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/collection-facets/smart-facets/heuristics/browser-language/browser-language-heuristic.ts

@@ -0,0 +1,27 @@
+import type { SmartQueryHeuristic, SmartFacet } from '../../models';
+
+export class BrowserLanguageHeuristic implements SmartQueryHeuristic {
+  async getRecommendedFacets(): Promise<SmartFacet[]> {
+    const browserLanguageCode = navigator.language;
+    const languageName =
+      BrowserLanguageHeuristic.getLanguageDisplayName(browserLanguageCode);
+    if (!languageName) return [];
+
+    return [
+      {
+        facets: [
+          {
+            facetType: 'language',
+            bucketKey: languageName,
+          },
+        ],
+      },
+    ];
+  }
+
+  private static getLanguageDisplayName(langCode: string): string | undefined {
+    // Strip off any script/region/variant codes for greater generality
+    const languageOnly = langCode.split('-')[0];
+    return new Intl.DisplayNames(['en'], { type: 'language' }).of(languageOnly);
+  }
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/collection-facets/smart-facets/heuristics/index.ts

@@ -0,0 +1,3 @@
+export { BrowserLanguageHeuristic } from './browser-language/browser-language-heuristic';
+export { QueryKeywordsHeuristic } from './query-keywords/query-keywords-heuristic';
+export { WikidataHeuristic } from './wikidata/wikidata-heuristic';

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/collection-facets/smart-facets/heuristics/query-keywords/query-keywords-heuristic.ts

@@ -0,0 +1,17 @@
+import type { SmartQueryHeuristic, SmartFacet } from '../../models';
+import { QUERY_KEYWORDS } from './query-keywords-map';
+
+// If the query contains X keyword but Y facet isn't selected, recommend facet Y
+export class QueryKeywordsHeuristic implements SmartQueryHeuristic {
+  async getRecommendedFacets(query: string): Promise<SmartFacet[]> {
+    const recommendations: SmartFacet[] = [];
+
+    for (const [keyword, facets] of Object.entries(QUERY_KEYWORDS)) {
+      if (query.includes(keyword)) {
+        recommendations.push(...facets);
+      }
+    }
+
+    return recommendations;
+  }
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/collection-facets/smart-facets/heuristics/query-keywords/query-keywords-map.ts

@@ -0,0 +1,70 @@
+import type { KeywordFacetMap, SmartFacet } from '../../models';
+
+const TEXTS: SmartFacet = {
+  facets: [{ facetType: 'mediatype', bucketKey: 'texts' }],
+};
+const AUDIO: SmartFacet = {
+  facets: [{ facetType: 'mediatype', bucketKey: 'audio' }],
+};
+const MOVIES: SmartFacet = {
+  facets: [{ facetType: 'mediatype', bucketKey: 'movies' }],
+};
+const IMAGE: SmartFacet = {
+  facets: [{ facetType: 'mediatype', bucketKey: 'image' }],
+};
+const SOFTWARE: SmartFacet = {
+  facets: [{ facetType: 'mediatype', bucketKey: 'software' }],
+};
+const ETREE: SmartFacet = {
+  facets: [{ facetType: 'mediatype', bucketKey: 'etree' }],
+};
+const WEB: SmartFacet = {
+  facets: [{ facetType: 'mediatype', bucketKey: 'web' }],
+};
+const DATA: SmartFacet = {
+  facets: [{ facetType: 'mediatype', bucketKey: 'data' }],
+};
+
+/**
+ * Map from keywords found in the search query to an array of
+ * likely-relevant "smart facets" for those keywords.
+ */
+export const QUERY_KEYWORDS: Readonly<KeywordFacetMap> = {
+  text: [TEXTS],
+  book: [TEXTS],
+  novel: [TEXTS],
+  magazine: [TEXTS],
+  newspaper: [TEXTS],
+  pdf: [TEXTS],
+  epub: [TEXTS],
+  audio: [AUDIO],
+  song: [AUDIO],
+  music: [AUDIO],
+  listen: [AUDIO],
+  podcast: [AUDIO],
+  radio: [AUDIO],
+  stream: [AUDIO, MOVIES],
+  video: [MOVIES],
+  movie: [MOVIES],
+  film: [MOVIES],
+  animation: [MOVIES],
+  youtube: [MOVIES],
+  image: [IMAGE],
+  photo: [IMAGE],
+  picture: [IMAGE],
+  painting: [IMAGE],
+  jpg: [IMAGE],
+  jpeg: [IMAGE],
+  png: [IMAGE],
+  gif: [IMAGE],
+  software: [SOFTWARE],
+  app: [SOFTWARE],
+  program: [SOFTWARE],
+  game: [SOFTWARE],
+  arcade: [SOFTWARE],
+  etree: [ETREE],
+  concert: [ETREE],
+  'live music': [ETREE],
+  'web crawl': [WEB],
+  dataset: [DATA],
+};

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/collection-facets/smart-facets/heuristics/wikidata/wikidata-entity-map.ts

@@ -0,0 +1,79 @@
+import type { KeywordFacetMap, SmartFacet } from '../../models';
+
+const WRITTEN_WORK_SMART_FACETS: SmartFacet[] = [
+  { facets: [{ facetType: 'mediatype', bucketKey: 'texts' }] },
+];
+
+const FILMMAKER_SMART_FACETS: SmartFacet[] = [
+  {
+    label: 'Films by __QUERY',
+    facets: [
+      { facetType: 'mediatype', bucketKey: 'movies' },
+      { facetType: 'creator', bucketKey: '__QUERY' },
+    ],
+  },
+];
+
+const AUTHOR_SMART_FACETS: SmartFacet[] = [
+  {
+    label: 'Writing by __QUERY',
+    facets: [
+      { facetType: 'mediatype', bucketKey: 'texts' },
+      { facetType: 'creator', bucketKey: '__QUERY' },
+    ],
+  },
+];
+
+const VISUAL_ARTIST_SMART_FACETS: SmartFacet[] = [
+  {
+    label: 'Images by __QUERY',
+    facets: [
+      { facetType: 'mediatype', bucketKey: 'image' },
+      { facetType: 'creator', bucketKey: '__QUERY' },
+    ],
+  },
+];
+
+const MUSICIAN_SMART_FACETS: SmartFacet[] = [
+  {
+    label: 'Music by __QUERY',
+    facets: [
+      { facetType: 'mediatype', bucketKey: 'audio' },
+      { facetType: 'creator', bucketKey: '__QUERY' },
+    ],
+  },
+];
+
+/**
+ * Map from Wikidata description keywords for a given entity to a
+ * set of likely-relevant "smart facets" for that query.
+ *
+ * The placeholder string "__QUERY" should be substituted for the actual
+ * queried entity when generating facet values.
+ */
+export const WIKIDATA_ENTITIES: Readonly<KeywordFacetMap> = {
+  'written work': WRITTEN_WORK_SMART_FACETS,
+  literature: WRITTEN_WORK_SMART_FACETS,
+  book: WRITTEN_WORK_SMART_FACETS,
+  novel: WRITTEN_WORK_SMART_FACETS,
+
+  filmmaker: FILMMAKER_SMART_FACETS,
+  director: FILMMAKER_SMART_FACETS,
+
+  author: AUTHOR_SMART_FACETS,
+  writer: AUTHOR_SMART_FACETS,
+  novelist: AUTHOR_SMART_FACETS,
+  essayist: AUTHOR_SMART_FACETS,
+  poet: AUTHOR_SMART_FACETS,
+
+  'visual artist': VISUAL_ARTIST_SMART_FACETS,
+  'graphic artist': VISUAL_ARTIST_SMART_FACETS,
+  photographer: VISUAL_ARTIST_SMART_FACETS,
+  painter: VISUAL_ARTIST_SMART_FACETS,
+
+  singer: MUSICIAN_SMART_FACETS,
+  songwriter: MUSICIAN_SMART_FACETS,
+  musician: MUSICIAN_SMART_FACETS,
+  composer: MUSICIAN_SMART_FACETS,
+  pianist: MUSICIAN_SMART_FACETS,
+};

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/collection-facets/smart-facets/heuristics/wikidata/wikidata-heuristic.ts

@@ -0,0 +1,93 @@
+import type { SmartQueryHeuristic, SmartFacet } from '../../models';
+import { WIKIDATA_ENTITIES } from './wikidata-entity-map';
+
+// If wikidata describes the top query result as X, recommend facet Y, e.g.:
+// X              Y
+// written work   mt:texts
+// film           mt:movies
+// author         mt:texts and creator:<query>
+// filmmaker      mt:movies and creator:<query>
+// photographer   mt:image and creator:<query>
+// visual artist  mt:image and creator:<query>
+// etc.
+export class WikidataHeuristic implements SmartQueryHeuristic {
+  private readonly WIKIDATA_BASE_URL = 'https://www.wikidata.org/w/api.php';
+
+  private readonly WIKIDATA_DEFAULT_ARGS =
+    '?action=wbsearchentities&format=json&language=en&uselang=en&origin=*&type=item&limit=5';
+
+  /**
+   * Returns the full URL for a Wikidata search for the given query
+   * @param query The query to search for
+   */
+  private getWikidataURL(query: string): string {
+    const urlQuery = encodeURIComponent(query);
+    return `${this.WIKIDATA_BASE_URL}${this.WIKIDATA_DEFAULT_ARGS}&search=${urlQuery}`;
+  }
+
+  /**
+   * Replaces query placeholders with an actual query string, within a collection of smart facets
+   * @param smartFacets The array of smart facets
+   * @param query The query string to replace placeholders with
+   * @returns A new array of smart facets with all query placeholders replaced
+   */
+  private replaceQueryPlaceholders(
+    smartFacets: SmartFacet[],
+    query: string,
+  ): SmartFacet[] {
+    return smartFacets.map(
+      smartFacet =>
+        ({
+          // Replace placeholders within the smart facet label
+          label: smartFacet.label?.replace('__QUERY', query),
+          // Replace placeholders within the facets themselves (buckets & display text)
+          facets: smartFacet.facets.map(facet => {
+            const replaced = {
+              ...facet,
+              bucketKey: facet.bucketKey.replace(
+                '__QUERY',
+                query.toLowerCase(),
+              ),
+            };
+
+            if (facet.displayText) {
+              replaced.displayText = replaced.displayText?.replace(
+                '__QUERY',
+                query,
+              );
+            }
+
+            return replaced;
+          }),
+        }) as SmartFacet,
+    );
+  }
+
+  /**
+   * @inheritdoc
+   */
+  async getRecommendedFacets(query: string): Promise<SmartFacet[]> {
+    const recommendations: SmartFacet[] = [];
+
+    try {
+      const wikidataURL = this.getWikidataURL(query);
+      const wikidataResponse = await fetch(wikidataURL);
+      const searchResults = await wikidataResponse.json();
+
+      for (const [keyword, facets] of Object.entries(WIKIDATA_ENTITIES)) {
+        const keywordRegex = new RegExp(`\\b${keyword}\\b`);
+        if (keywordRegex.test(searchResults.search[0]?.description)) {
+          const entityName = searchResults.search[0].label;
+          recommendations.push(
+            ...this.replaceQueryPlaceholders(facets, entityName),
+          );
+        }
+      }
+
+      return recommendations;
+    } catch (err) {
+      console.warn(err);
+      return [];
+    }
+  }
+}

package/.claude/worktrees/WEBDEV-9119-migrate-to-pnpm/src/collection-facets/smart-facets/models.ts

@@ -0,0 +1,36 @@
+import type { FacetEventDetails, FacetOption } from '../../models';
+
+export interface FacetRef {
+  facetType: FacetOption;
+  bucketKey: string;
+  displayText?: string;
+}
+
+interface LabeledSmartFacet {
+  label: string;
+  facets: FacetRef[];
+  selected?: boolean;
+}
+
+interface UnlabeledSmartFacet {
+  label?: string;
+  facets: [FacetRef];
+  selected?: boolean;
+}
+
+export type SmartFacet = LabeledSmartFacet | UnlabeledSmartFacet;
+
+export interface SmartFacetEvent {
+  smartFacet: SmartFacet;
+  details: FacetEventDetails[];
+}
+
+export type KeywordFacetMap = Record<string, SmartFacet[]>;
+
+export interface SmartQueryHeuristic {
+  /**
+   * Resolves to a recommended set of facets to apply for the given query
+   * @param query The search query to recommend facets for
+   */
+  getRecommendedFacets(query: string): Promise<SmartFacet[]>;
+}