@internetarchive/collection-browser 4.8.0 → 4.8.1-alpha-webdev9189.0

package/src/collection-facets/page-window.ts

@@ -1,247 +0,0 @@
-import type { ReactiveController, ReactiveControllerHost } from 'lit';
-
-export type PageWindowConfig = {
-  /** Width in px of every column. Columns are uniform. */
-  colWidth: number;
-
-  /** Total number of columns in the dataset. */
-  total: number;
-
-  /** Pages kept mounted on each side of the visible ones. Defaults to 1. */
-  buffer?: number;
-
-  /**
-   * Called each time the scroller comes to rest (or is re-laid out), with the
-   * page it rests on. Fires even when that page hasn't changed.
-   */
-  onRest?: (page: number) => void;
-};
-
-const supportsScrollEnd = 'onscrollend' in window;
-
-/**
- * Windowing controller for a horizontal scroller of fixed-width columns that
- * snaps to page boundaries. Tracks which pages should be in the DOM (`first`
- * through `last`) and which page the scroller last came to rest on.
- *
- * All positions are arithmetic on `colWidth`; the only measurement is the
- * scroller's width, which comes from a ResizeObserver.
- *
- * See docs/design/column-virtualization.md before changing this, especially
- * its invariants.
- */
-export class PageWindow implements ReactiveController {
-  /** Index of the first mounted page. */
-  first = 0;
-
-  /** Index of the last mounted page, or -1 when nothing is mounted. */
-  last = -1;
-
-  /** How many columns fit in the scroller, derived from its measured width. */
-  colsPerPage = 1;
-
-  /** The page the scroller last came to rest on. */
-  currentPage = 0;
-
-  private scroller?: HTMLElement;
-
-  private viewportW = 0;
-
-  private frame = 0;
-
-  private landFrame = 0;
-
-  private endTimer = 0;
-
-  private ro?: ResizeObserver;
-
-  /** Page to realign to once the host has re-rendered at a new page width. */
-  private realignTo?: number;
-
-  /** Whether to re-check the resting page once the host has re-rendered. */
-  private relandAfterUpdate = false;
-
-  constructor(
-    private host: ReactiveControllerHost,
-    private cfg: PageWindowConfig,
-  ) {
-    host.addController(this);
-  }
-
-  get pageWidth(): number {
-    return this.cfg.colWidth * this.colsPerPage;
-  }
-
-  get pageCount(): number {
-    return Math.ceil(this.cfg.total / this.colsPerPage);
-  }
-
-  get totalWidth(): number {
-    return this.cfg.colWidth * this.cfg.total;
-  }
-
-  /**
-   * Width of page `i`. Every page is `pageWidth` except a partial last page,
-   * which is trimmed so that nothing extends the scroll area past `totalWidth`.
-   */
-  pageSpan(i: number): number {
-    return Math.min(this.pageWidth, this.totalWidth - i * this.pageWidth);
-  }
-
-  /** Updates the number of columns, e.g. when the dataset is filtered. */
-  setTotal(total: number): void {
-    if (total === this.cfg.total) return;
-    this.cfg.total = total;
-    this.recompute(true);
-    // The sizer hasn't resized yet, so wait for the host to render before
-    // reading where the scroller rests.
-    this.relandAfterUpdate = true;
-  }
-
-  /** Scrolls so that `page` sits at the start of the viewport. */
-  scrollToPage(page: number, behavior: ScrollBehavior = 'auto'): void {
-    const target = Math.max(0, Math.min(page, this.pageCount - 1));
-    this.scroller?.scrollTo({ left: target * this.pageWidth, behavior });
-  }
-
-  /** Ref callback for the scroll container. */
-  attach = (el?: Element): void => {
-    const next = el instanceof HTMLElement ? el : undefined;
-    if (next === this.scroller) return;
-    this.detach();
-    if (!next) return;
-
-    this.scroller = next;
-    next.addEventListener('scroll', this.onScroll, { passive: true });
-    if (supportsScrollEnd) {
-      next.addEventListener('scrollend', this.onScrollEnd);
-    } else {
-      next.addEventListener('scroll', this.onScrollIdle, { passive: true });
-    }
-
-    this.ro = new ResizeObserver(([e]) => this.onResize(e.contentRect.width));
-    this.ro.observe(next);
-  };
-
-  hostUpdated(): void {
-    const el = this.scroller;
-    if (!el) return;
-    // A resize changed the page width. The host has now moved the snap stubs,
-    // so put the page that held the anchor column back at the start.
-    if (this.realignTo !== undefined) {
-      const target = this.realignTo * this.pageWidth;
-      // After a layout change WebKit re-snaps to the snap point with the same
-      // index as before, which is now a different column. Assigning the
-      // position the scroller already has is a no-op that doesn't update that
-      // index, so nudge it first.
-      if (el.scrollLeft === target) el.scrollLeft = target + 1;
-      el.scrollLeft = target;
-      this.realignTo = undefined;
-      this.relandAfterUpdate = true;
-    }
-    if (this.relandAfterUpdate && !this.landFrame) {
-      this.relandAfterUpdate = false;
-      // Next frame, so as not to update the host again from inside its update
-      this.landFrame = requestAnimationFrame(() => {
-        this.landFrame = 0;
-        this.land();
-      });
-    }
-  }
-
-  hostDisconnected(): void {
-    this.detach();
-  }
-
-  private detach(): void {
-    const el = this.scroller;
-    if (!el) return;
-    el.removeEventListener('scroll', this.onScroll);
-    el.removeEventListener('scroll', this.onScrollIdle);
-    el.removeEventListener('scrollend', this.onScrollEnd);
-    this.ro?.disconnect();
-    this.ro = undefined;
-    if (this.frame) cancelAnimationFrame(this.frame);
-    if (this.landFrame) cancelAnimationFrame(this.landFrame);
-    this.frame = 0;
-    this.landFrame = 0;
-    clearTimeout(this.endTimer);
-    this.scroller = undefined;
-  }
-
-  private onResize(width: number): void {
-    const el = this.scroller;
-    if (!el) return;
-    this.viewportW = width;
-
-    const colsPerPage = Math.max(1, Math.floor(width / this.cfg.colWidth));
-    if (colsPerPage === this.colsPerPage) {
-      this.recompute();
-      return;
-    }
-
-    // Columns never move (column c always starts at c * colWidth); only the
-    // page boundaries do. Keep the leftmost visible column on screen by
-    // realigning to whichever new page contains it.
-    const anchorCol = Math.round(el.scrollLeft / this.cfg.colWidth);
-    this.colsPerPage = colsPerPage;
-    this.realignTo = Math.floor(anchorCol / colsPerPage);
-    this.recompute(true);
-  }
-
-  private onScroll = (): void => {
-    if (this.frame) return;
-    this.frame = requestAnimationFrame(() => {
-      this.frame = 0;
-      this.recompute();
-    });
-  };
-
-  /** Fallback for browsers without `scrollend`: treat 120ms of quiet as rest. */
-  private onScrollIdle = (): void => {
-    clearTimeout(this.endTimer);
-    this.endTimer = window.setTimeout(this.onScrollEnd, 120);
-  };
-
-  private onScrollEnd = (): void => {
-    this.land();
-  };
-
-  private recompute(force = false): void {
-    const el = this.scroller;
-    if (!el) return;
-    const pw = this.pageWidth;
-    const buf = this.cfg.buffer ?? 1;
-    const left = el.scrollLeft;
-    const first = Math.max(0, Math.floor(left / pw) - buf);
-    // Floor on both edges, so that first and last shift together at each page
-    // boundary rather than one just before it and one just after.
-    const last = Math.min(
-      this.pageCount - 1,
-      Math.floor((left + this.viewportW) / pw) + buf,
-    );
-    // Most scroll events end here: the window only changes at page boundaries
-    if (!force && first === this.first && last === this.last) return;
-    this.first = first;
-    this.last = last;
-    this.host.requestUpdate();
-  }
-
-  /** Records which page the scroller is resting on. */
-  private land(): void {
-    const el = this.scroller;
-    if (!el) return;
-    const left = el.scrollLeft;
-    const maxLeft = this.totalWidth - this.viewportW;
-    // A partial last page can't reach its own snap point, so resting at the
-    // far end counts as landing on the last page.
-    const atEnd = left >= maxLeft - 1;
-    const page = atEnd ? this.pageCount - 1 : Math.round(left / this.pageWidth);
-    const clamped = Math.max(0, Math.min(page, this.pageCount - 1));
-    if (clamped !== this.currentPage) {
-      this.currentPage = clamped;
-      this.host.requestUpdate();
-    }
-    this.cfg.onRest?.(clamped);
-  }
-}

package/src/collection-facets/smart-facets/dedupe.ts

@@ -1,44 +0,0 @@
-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/src/collection-facets/smart-facets/heuristics/browser-language/browser-language-heuristic.ts

@@ -1,27 +0,0 @@
-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/src/collection-facets/smart-facets/heuristics/index.ts

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

package/src/collection-facets/smart-facets/heuristics/query-keywords/query-keywords-heuristic.ts

@@ -1,17 +0,0 @@
-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/src/collection-facets/smart-facets/heuristics/query-keywords/query-keywords-map.ts

@@ -1,70 +0,0 @@
-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/src/collection-facets/smart-facets/heuristics/wikidata/wikidata-entity-map.ts

@@ -1,79 +0,0 @@
-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/src/collection-facets/smart-facets/heuristics/wikidata/wikidata-heuristic.ts

@@ -1,93 +0,0 @@
-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/src/collection-facets/smart-facets/models.ts

@@ -1,36 +0,0 @@
-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[]>;
-}