@sarimarcus/content-sites-ui 0.17.0 → 0.19.0

package/src/search/searchPage.ts

@@ -0,0 +1,591 @@
+// Client controller of SearchPage: Pagefind search with type chips (a meta filter, applied client-side), an optional
+// audience row (a native Pagefind filter), URL state, load-more paging and search analytics. The route calls
+// initSearchPage once from its <script>; a hoisted script cannot read component props, so taxonomy and copy come in here.
+import { appendResults, type PagefindResultFragment, type SearchTaxonomy, type SearchTypeMeta } from './renderResult.ts';
+
+export interface SearchPageType extends SearchTypeMeta {
+  pluralLabel: string;
+  iconName: string;
+}
+
+export interface SearchPageStrings {
+  heroEyebrow: string;
+  heroHeading: string;
+  heroSubhead: string;
+  inputPlaceholder: string;
+  inputLabel: string;
+  filterAllLabel: string;
+  filterGroupLabel: string;
+  resultsHeadingOne: string;
+  resultsHeadingMany: string;
+  resultsHeadingFiltered: string;
+  loadingLabel: string;
+  loadMoreLabel: string;
+  emptySuggestionsLabel: string;
+  zeroHeading: string;
+  zeroSubhead: string;
+  zeroFallbackLabel: string;
+  filterEmptyHeading: string;
+  filterEmptyClearLabel: string;
+  errorHeading: string;
+  errorSubhead: string;
+  errorRetryLabel: string;
+  /** Accessible name of the clear button. */
+  clearLabel: string;
+  /** Live-region announcements; `{q}` is the query, `{n}` the count. */
+  announceZero: string;
+  announceCategoryEmpty: string;
+  announceResultsOne: string;
+  announceResultsMany: string;
+  announceError: string;
+  /** Audience row copy, required when the page renders `audienceFacets`. */
+  audienceGroupLabel?: string;
+  audienceRowLabel?: string;
+  audienceAllLabel?: string;
+  resultsHeadingAudience?: string;
+  filterEmptyAudienceHeading?: string;
+  announceAudienceEmpty?: string;
+  /** `{n}` is replaced by the count. */
+  filterNoteOne?: string;
+  filterNoteMany?: string;
+  filterNoteAction?: string;
+}
+
+export type SearchState = 'empty' | 'loading' | 'results' | 'zero' | 'filter-empty' | 'error';
+
+export interface SearchPageConfig<T extends string> extends SearchTaxonomy<T> {
+  types: Record<T, SearchPageType>;
+  strings: SearchPageStrings;
+  pageSize?: number;
+  debounceMs?: number;
+}
+
+declare global {
+  interface Window {
+    track?: (eventName: string, params?: Record<string, unknown>) => void;
+  }
+}
+
+type PagefindHandle = { id: string; data: () => Promise<PagefindResultFragment> };
+type PagefindModule = {
+  init: () => Promise<void>;
+  search: (
+    q: string,
+    options?: { filters?: Record<string, string> },
+  ) => Promise<{
+    results: PagefindHandle[];
+    /** Matches for the query BEFORE any filter — how many the filter removed. */
+    unfilteredResultCount?: number;
+    /** Per-filter-value counts for this query, i.e. what each chip would yield. */
+    totalFilters?: Record<string, Record<string, number>>;
+  }>;
+};
+
+export function initSearchPage<T extends string>(config: SearchPageConfig<T>): void {
+  const { types, strings, pageSize = 12, debounceMs = 140 } = config;
+  const taxonomy: SearchTaxonomy<T> = { types, resolveType: config.resolveType, untitled: config.untitled };
+  const isSearchType = (value: string | null | undefined): value is T => value != null && value in types;
+
+  const input = document.getElementById('search-input') as HTMLInputElement;
+  const form = input.closest('form') as HTMLFormElement;
+  const clearButton = document.querySelector<HTMLButtonElement>('[data-search-clear]')!;
+  const filtersRoot = document.querySelector<HTMLElement>('.search-filters:not(.search-filters--audience)');
+  const audienceRoot = document.querySelector<HTMLElement>('.search-filters--audience');
+  const region = document.getElementById('search-results-region')!;
+  const announceEl = document.getElementById('search-announce')!;
+  const headingEl = document.querySelector<HTMLElement>('[data-search-results-heading]')!;
+  const listEl = document.querySelector<HTMLUListElement>('[data-search-results-list]')!;
+  const loadMoreBtn = document.querySelector<HTMLButtonElement>('[data-search-load-more]')!;
+  const zeroHeadingEl = document.querySelector<HTMLElement>('[data-search-zero-heading]')!;
+  const filterNoteEl = document.querySelector<HTMLElement>('[data-search-filter-note]')!;
+  const filterEmptyHeadingEl = document.querySelector<HTMLElement>(
+    '[data-search-filter-empty-heading]',
+  )!;
+
+  // Single source of truth for valid audience values: the chips the server
+  // rendered, which came from measured corpus counts.
+  const KNOWN_AUDIENCES = new Set(
+    Array.from(audienceRoot?.querySelectorAll<HTMLButtonElement>('[data-search-audience]') ?? [])
+      .map((b) => b.dataset.searchAudience || '')
+      .filter(Boolean),
+  );
+
+  const states = {} as Record<SearchState, HTMLElement>;
+  document.querySelectorAll<HTMLElement>('[data-search-state]').forEach((el) => {
+    const key = el.dataset.searchState as SearchState | undefined;
+    if (key) states[key] = el;
+  });
+
+  let pagefindAPI: PagefindModule | null = null;
+  let activeType: T | null = null;
+  let activeAudience: string | null = null;
+  let renderedCount = 0;
+  // Result handles are cheap (no network); fragments are materialized lazily.
+  let cachedHandles: PagefindHandle[] = [];
+  let cachedFragments: PagefindResultFragment[] = [];
+  let searchToken = 0;
+  let lastQuery = '';
+  let lastType: T | null = null;
+  let lastAudience: string | null = null;
+
+  function readURL() {
+    const params = new URLSearchParams(window.location.search);
+    const q = params.get('q')?.trim() ?? '';
+    const t = params.get('type');
+    const focus = params.get('focus') === '1';
+    const type = isSearchType(t) ? t : null;
+    // Validated against the rendered chips, so a hand-typed value that carries
+    // no content cannot put the page in a permanently empty filtered state.
+    const rawAudience = params.get('audience');
+    const audience = rawAudience && KNOWN_AUDIENCES.has(rawAudience) ? rawAudience : null;
+    return { q, type, audience, focus };
+  }
+
+  function writeURL(q: string, type: T | null, audience: string | null) {
+    const params = new URLSearchParams();
+    if (q) params.set('q', q);
+    if (type) params.set('type', type);
+    if (audience) params.set('audience', audience);
+    const qs = params.toString();
+    const next = qs ? `${window.location.pathname}?${qs}` : window.location.pathname;
+    window.history.replaceState(null, '', next);
+  }
+
+  function showState(name: SearchState, announceText?: string) {
+    (Object.keys(states) as SearchState[]).forEach((key) => {
+      states[key].hidden = key !== name;
+    });
+    region.setAttribute('aria-busy', String(name === 'loading'));
+    if (filtersRoot) filtersRoot.hidden = name === 'empty';
+    if (audienceRoot) audienceRoot.hidden = name === 'empty';
+    // Keep announcer quiet during loading/empty; only announce outcomes.
+    if (announceText !== undefined) {
+      announceEl.textContent = announceText;
+    } else if (name === 'loading' || name === 'empty') {
+      announceEl.textContent = '';
+    }
+  }
+
+  function updateFilterChips(type: T | null) {
+    filtersRoot
+      ?.querySelectorAll<HTMLButtonElement>('[data-search-filter]')
+      .forEach((btn) => {
+        const isActive = (btn.dataset.searchFilter || null) === (type || null);
+        btn.classList.toggle('search-chip--active', isActive);
+        btn.setAttribute('aria-pressed', String(isActive));
+      });
+  }
+
+  function updateAudienceChips(audience: string | null) {
+    audienceRoot
+      ?.querySelectorAll<HTMLButtonElement>('[data-search-audience]')
+      .forEach((btn) => {
+        const isActive = (btn.dataset.searchAudience || null) === (audience || null);
+        btn.classList.toggle('search-chip--active', isActive);
+        btn.setAttribute('aria-pressed', String(isActive));
+      });
+  }
+
+  /**
+   * Repoint the chip counts at the current query. Server-rendered counts are
+   * corpus-wide item counts, which read as result counts and are off by orders
+   * of magnitude once a query is typed ("Couples 133" then 3 results). Pagefind
+   * returns per-value counts for the query in `totalFilters`, so use those and
+   * fall back to the corpus number when there is no query.
+   */
+  function updateAudienceCounts(totals?: Record<string, number>) {
+    audienceRoot
+      ?.querySelectorAll<HTMLButtonElement>('[data-search-audience]')
+      .forEach((btn) => {
+        const value = btn.dataset.searchAudience;
+        const countEl = btn.querySelector<HTMLElement>('.search-chip__count');
+        if (!value || !countEl) return; // the "Anyone" chip carries no count
+        const corpus = btn.dataset.searchAudienceTotal ?? '';
+        const n = totals ? totals[value] ?? 0 : Number(corpus);
+        countEl.textContent = String(n);
+        btn.classList.toggle('search-chip--empty', totals !== undefined && n === 0);
+      });
+  }
+
+  function renderFilterNote(hidden: number) {
+    if (hidden <= 0) {
+      filterNoteEl.hidden = true;
+      filterNoteEl.replaceChildren();
+      return;
+    }
+    filterNoteEl.replaceChildren();
+    filterNoteEl.appendChild(
+      document.createTextNode(
+        hidden === 1 ? strings.filterNoteOne ?? '' : (strings.filterNoteMany ?? '').replace('{n}', String(hidden)),
+      ),
+    );
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'search-filter-note__action';
+    btn.textContent = strings.filterNoteAction ?? '';
+    btn.setAttribute('data-search-clear-audience', '');
+    filterNoteEl.appendChild(btn);
+    filterNoteEl.hidden = false;
+  }
+
+  function audienceLabel(value: string): string {
+    const btn = audienceRoot?.querySelector<HTMLButtonElement>(
+      `[data-search-audience="${value}"] span`,
+    );
+    return btn?.textContent?.trim() || value;
+  }
+
+  function renderHeading(
+    el: HTMLElement,
+    count: number,
+    query: string,
+    typeFilter: T | null,
+    audienceFilter: string | null,
+  ) {
+    el.replaceChildren();
+    const prefix =
+      count === 1 ? strings.resultsHeadingOne : `${count}${strings.resultsHeadingMany}`;
+    el.appendChild(document.createTextNode(prefix));
+    const queryStrong = document.createElement('strong');
+    queryStrong.textContent = `“${query}”`;
+    el.appendChild(queryStrong);
+    if (typeFilter) {
+      el.appendChild(document.createTextNode(strings.resultsHeadingFiltered));
+      const typeStrong = document.createElement('strong');
+      typeStrong.textContent = types[typeFilter].pluralLabel;
+      el.appendChild(typeStrong);
+    }
+    if (audienceFilter) {
+      el.appendChild(document.createTextNode(strings.resultsHeadingAudience ?? ''));
+      const audienceStrong = document.createElement('strong');
+      audienceStrong.textContent = audienceLabel(audienceFilter);
+      el.appendChild(audienceStrong);
+    }
+  }
+
+  function renderZeroHeading(el: HTMLElement, query: string) {
+    el.replaceChildren();
+    el.appendChild(document.createTextNode(strings.zeroHeading));
+    const strong = document.createElement('strong');
+    strong.textContent = `“${query}”`;
+    el.appendChild(strong);
+  }
+
+  async function getPagefind(): Promise<PagefindModule> {
+    if (pagefindAPI) return pagefindAPI;
+    // @ts-expect-error — /pagefind/pagefind.js is emitted by the build, so it
+    // cannot resolve at type-check time. Runtime path is correct.
+    const mod = (await import(/* @vite-ignore */ '/pagefind/pagefind.js')) as PagefindModule;
+    await mod.init();
+    pagefindAPI = mod;
+    return pagefindAPI;
+  }
+
+  async function runSearch(
+    query: string,
+    typeFilter: T | null,
+    audienceFilter: string | null = null,
+  ) {
+    // Skip if neither query nor either filter changed since the last invocation.
+    if (query === lastQuery && typeFilter === lastType && audienceFilter === lastAudience) return;
+    lastQuery = query;
+    lastType = typeFilter;
+    lastAudience = audienceFilter;
+
+    writeURL(query, typeFilter, audienceFilter);
+    const myToken = ++searchToken;
+
+    if (!query) {
+      updateAudienceCounts(undefined); // back to corpus counts
+      renderFilterNote(0);
+      showState('empty');
+      return;
+    }
+
+    showState('loading');
+
+    try {
+      const pf = await getPagefind();
+      // `audience` IS a native Pagefind filter, so it narrows the result set in
+      // the index rather than in JS — no fragment fetch to count it.
+      const result = await pf.search(
+        query,
+        audienceFilter ? { filters: { audience: audienceFilter } } : undefined,
+      );
+      if (myToken !== searchToken) return;
+
+      cachedHandles = result.results;
+
+      // Query-aware chip counts. `totalFilters` carries per-value counts FOR THIS
+      // QUERY (verified: couples=41 on "salmorejo" vs 156 on "cordoba"), and it
+      // deliberately ignores the audience filter itself, so one filtered search
+      // yields every chip's count. Pagefind only populates it when a filter is
+      // applied, though — so with no audience selected, harvest the same numbers
+      // from one extra index search whose results are discarded. Index-local, no
+      // network, and it keeps the chips from showing corpus counts next to a
+      // query's results ("Couples 133" above 3 salmorejo matches).
+      let audienceTotals = result.totalFilters?.audience;
+      if (!audienceTotals && KNOWN_AUDIENCES.size > 0) {
+        try {
+          const probe = await pf.search(query, {
+            filters: { audience: [...KNOWN_AUDIENCES][0] },
+          });
+          if (myToken !== searchToken) return;
+          audienceTotals = probe.totalFilters?.audience;
+        } catch {
+          // Counts simply stay as they were — not worth failing a search over.
+        }
+      }
+      updateAudienceCounts(audienceTotals);
+
+      const unfilteredCount = result.unfilteredResultCount ?? cachedHandles.length;
+      renderFilterNote(audienceFilter ? unfilteredCount - cachedHandles.length : 0);
+
+      if (cachedHandles.length === 0) {
+        // With a filter on, offer the clear-filter affordance instead of the
+        // dead-end zero state: the query itself may be perfectly good.
+        if (audienceFilter) {
+          filterEmptyHeadingEl.textContent = strings.filterEmptyAudienceHeading ?? strings.filterEmptyHeading;
+          renderFilterNote(0);
+          showState('filter-empty', strings.announceAudienceEmpty ?? '');
+          return;
+        }
+        renderZeroHeading(zeroHeadingEl, query);
+        showState('zero', strings.announceZero.replace('{q}', () => query));
+        // No `search_audience_filter` here: the audience branch above returns
+        // first, so this event is only ever reached with no audience filter on.
+        window.track?.('search_zero_results', {
+          search_term: query,
+          search_type_filter: typeFilter ?? '',
+        });
+        return;
+      }
+
+      if (typeFilter) {
+        // `type` is NOT a Pagefind filter — it lives in each fragment's meta,
+        // so it can only be applied after materializing them. That is why this
+        // branch fetches all handles while the audience filter above does not.
+        // Making it native would mean emitting data-pagefind-filter="type:…"
+        // from every detail template.
+        const all = await Promise.all(cachedHandles.map((h) => h.data()));
+        if (myToken !== searchToken) return;
+        cachedFragments = all.filter((f) => taxonomy.resolveType(f.meta) === typeFilter);
+
+        if (cachedFragments.length === 0) {
+          filterEmptyHeadingEl.textContent = strings.filterEmptyHeading;
+          showState('filter-empty', strings.announceCategoryEmpty);
+          return;
+        }
+
+        listEl.replaceChildren();
+        appendResults(listEl, cachedFragments.slice(0, pageSize), 0, taxonomy);
+        renderedCount = Math.min(pageSize, cachedFragments.length);
+        loadMoreBtn.hidden = cachedFragments.length <= pageSize;
+        renderHeading(headingEl, cachedFragments.length, query, typeFilter, audienceFilter);
+      } else {
+        // No filter: fetch only the fragments we render. Load-more fetches more.
+        const firstBatch = await Promise.all(
+          cachedHandles.slice(0, pageSize).map((h) => h.data()),
+        );
+        if (myToken !== searchToken) return;
+        cachedFragments = firstBatch;
+
+        listEl.replaceChildren();
+        appendResults(listEl, firstBatch, 0, taxonomy);
+        renderedCount = firstBatch.length;
+        loadMoreBtn.hidden = cachedHandles.length <= pageSize;
+        renderHeading(headingEl, cachedHandles.length, query, typeFilter, audienceFilter);
+      }
+
+      const resultCount = typeFilter ? cachedFragments.length : cachedHandles.length;
+      const announce = resultCount === 1 ? strings.announceResultsOne : strings.announceResultsMany;
+      showState('results', announce.replace('{n}', String(resultCount)).replace('{q}', () => query));
+
+      window.track?.('search_query', {
+        search_term: query,
+        search_type_filter: typeFilter ?? '',
+        ...(audienceRoot ? { search_audience_filter: audienceFilter ?? '' } : {}),
+        search_results_count: resultCount,
+      });
+    } catch (err) {
+      console.error('[search] failed', err);
+      if (myToken !== searchToken) return;
+      showState('error', strings.announceError);
+    }
+  }
+
+  function debounce<A extends unknown[]>(
+    fn: (...args: A) => void,
+    ms: number,
+  ): (...args: A) => void {
+    let t: number | undefined;
+    return (...args: A) => {
+      clearTimeout(t);
+      t = window.setTimeout(() => fn(...args), ms);
+    };
+  }
+
+  const debouncedRun = debounce(runSearch, debounceMs);
+
+  form.addEventListener('submit', (e) => e.preventDefault());
+
+  input.addEventListener('input', () => {
+    const q = input.value.trim();
+    clearButton.hidden = q.length === 0;
+    debouncedRun(q, activeType, activeAudience);
+  });
+
+  input.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape' && input.value) {
+      e.preventDefault();
+      input.value = '';
+      clearButton.hidden = true;
+      runSearch('', activeType, activeAudience);
+    }
+  });
+
+  clearButton.addEventListener('click', () => {
+    input.value = '';
+    clearButton.hidden = true;
+    input.focus();
+    runSearch('', activeType, activeAudience);
+  });
+
+  filtersRoot?.addEventListener('click', (e) => {
+    const btn = (e.target as HTMLElement).closest<HTMLButtonElement>('[data-search-filter]');
+    if (!btn) return;
+    const raw = btn.dataset.searchFilter || '';
+    const newType = isSearchType(raw) ? raw : null;
+    activeType = newType;
+    updateFilterChips(newType);
+    runSearch(input.value.trim(), newType, activeAudience);
+  });
+
+  audienceRoot?.addEventListener('click', (e) => {
+    const btn = (e.target as HTMLElement).closest<HTMLButtonElement>('[data-search-audience]');
+    if (!btn) return;
+    const raw = btn.dataset.searchAudience || '';
+    const newAudience = KNOWN_AUDIENCES.has(raw) ? raw : null;
+    activeAudience = newAudience;
+    updateAudienceChips(newAudience);
+    runSearch(input.value.trim(), activeType, newAudience);
+  });
+
+  region.addEventListener('click', (e) => {
+    const target = e.target as HTMLElement;
+
+    const sugBtn = target.closest<HTMLButtonElement>('[data-search-suggest]');
+    if (sugBtn) {
+      const q = sugBtn.dataset.searchSuggest || '';
+      input.value = q;
+      clearButton.hidden = q.length === 0;
+      input.focus();
+      runSearch(q, activeType, activeAudience);
+      return;
+    }
+
+    if (target.closest<HTMLElement>('[data-search-clear-audience]')) {
+      // Narrower than [data-search-clear-filter]: the note is specifically about
+      // what the AUDIENCE filter removed, so it must not also drop a type filter
+      // the reader deliberately set.
+      activeAudience = null;
+      updateAudienceChips(null);
+      runSearch(input.value.trim(), activeType, null);
+      return;
+    }
+
+    if (target.closest<HTMLElement>('[data-search-clear-filter]')) {
+      // Clears BOTH filters: the empty state does not say which one excluded
+      // everything, so clearing only one can leave the page still empty.
+      activeType = null;
+      activeAudience = null;
+      updateFilterChips(null);
+      updateAudienceChips(null);
+      runSearch(input.value.trim(), null, null);
+      return;
+    }
+
+    if (target.closest<HTMLElement>('[data-search-retry]')) {
+      lastQuery = '';
+      lastType = null;
+      lastAudience = null;
+      runSearch(input.value.trim(), activeType, activeAudience);
+    }
+  });
+
+  loadMoreBtn.addEventListener('click', async () => {
+    if (activeType) {
+      // All type-filtered fragments are already in cachedFragments. An audience
+      // filter needs no branch here: it narrowed cachedHandles server-side, so
+      // the paging path below is already correct for it.
+      const next = cachedFragments.slice(renderedCount, renderedCount + pageSize);
+      if (next.length === 0) return;
+      appendResults(listEl, next, renderedCount, taxonomy);
+      renderedCount += next.length;
+      if (renderedCount >= cachedFragments.length) loadMoreBtn.hidden = true;
+      return;
+    }
+
+    const nextHandles = cachedHandles.slice(renderedCount, renderedCount + pageSize);
+    if (nextHandles.length === 0) return;
+    const fragments = await Promise.all(nextHandles.map((h) => h.data()));
+    cachedFragments.push(...fragments);
+    appendResults(listEl, fragments, renderedCount, taxonomy);
+    renderedCount += fragments.length;
+    if (renderedCount >= cachedHandles.length) loadMoreBtn.hidden = true;
+  });
+
+  listEl.addEventListener('click', (e) => {
+    const link = (e.target as HTMLElement).closest<HTMLAnchorElement>(
+      '[data-search-result-link]',
+    );
+    if (!link) return;
+    const card = link.closest<HTMLElement>('.search-card');
+    window.track?.('search_result_click', {
+      search_term: input.value.trim(),
+      result_position: card ? Number(card.dataset.index ?? 0) + 1 : 0,
+      result_url: link.href,
+    });
+  });
+
+  window.addEventListener('popstate', () => {
+    const next = readURL();
+    input.value = next.q;
+    clearButton.hidden = next.q.length === 0;
+    activeType = next.type;
+    activeAudience = next.audience;
+    updateFilterChips(next.type);
+    updateAudienceChips(next.audience);
+    runSearch(next.q, next.type, next.audience);
+  });
+
+  const initial = readURL();
+  if (initial.q) {
+    input.value = initial.q;
+    clearButton.hidden = false;
+  }
+  activeType = initial.type;
+  activeAudience = initial.audience;
+  updateFilterChips(initial.type);
+  updateAudienceChips(initial.audience);
+  if (initial.q) {
+    runSearch(initial.q, initial.type, initial.audience);
+  }
+  if (initial.focus || !initial.q) {
+    const claimFocus = () => {
+      if (document.activeElement === input) return;
+      input.focus({ preventScroll: true });
+      if (input.value) {
+        input.setSelectionRange(input.value.length, input.value.length);
+      }
+    };
+    requestAnimationFrame(claimFocus);
+    // Cookie consent banner may steal focus ~1.5s after load (deferred init).
+    // Reclaim once if the user hasn't moved focus elsewhere.
+    if (initial.focus) {
+      window.setTimeout(() => {
+        if (document.activeElement === document.body) claimFocus();
+      }, 1700);
+    }
+  }
+}