app/routes/search.tsx

Functions

Imports

It imports app/components/ask-panel.tsx, app/components/enhance.tsx, app/components/search-form.tsx, app/components/shell-footer.tsx, app/components/site-header.tsx, app/db/index.ts, app/kb/search-bases.mjs, app/lib/context.ts, app/lib/error-message.mjs, app/lib/negotiate.mjs, app/lib/search/ask.server.ts, app/lib/search/query.mjs, app/lib/search/search.server.ts, app/lib/search/zero-result.server.ts, app/lib/seo.ts. No module of this repo imports it.

Source

1import { Link, data } from "react-router";
2
3import { AskMount } from "~/components/ask-panel";
4import { Enhance } from "~/components/enhance";
5import { SearchForm } from "~/components/search-form";
6import { ShellFooter } from "~/components/shell-footer";
7import { SiteHeader } from "~/components/site-header";
8import { nextScheduledPublishAt } from "~/db";
9import { getEnv, getExecutionContext } from "~/lib/context";
10import { prefersType } from "~/lib/negotiate.mjs";
11import { hasFilters } from "~/lib/search/query.mjs";
12import { askAvailable } from "~/lib/search/ask.server";
13import { recordZeroResult } from "~/lib/search/zero-result.server";
14import { SEARCH_BASES, baseLabel } from "~/kb/search-bases.mjs";
15import {
16  parseSort,
17  search,
18  zeroState,
19  type MatchReason,
20  type SearchHit,
21} from "~/lib/search/search.server";
22import {
23  EDGE_CACHE_HEADER,
24  NO_STORE_CACHE_CONTROL,
25  HTML_VARY_ACCEPT,
26  cacheTags,
27  scheduledEdgeCacheControl,
28  SHARED_CACHE_CONTROL,
29  SITE,
30  SITE_ORIGIN,
31  pageMeta,
32} from "~/lib/seo";
33import type { Route } from "./+types/search";
34
35import "~/styles/blog-search.css";
36import "~/styles/search-page.css";
37import "~/styles/ask.css";
38import "~/styles/search-facets.css";
39import { errorMessage } from "~/lib/error-message.mjs";
40
41const PAGE_SIZE = 10;
42
43function readParams(url: URL) {
44  const page = Number.parseInt(url.searchParams.get("page") ?? "1", 10);
45  return {
46    q: url.searchParams.get("q") ?? "",
47    type: url.searchParams.get("type"),
48    base: url.searchParams.get("base"),
49    tag: url.searchParams.get("tag"),
50    year: url.searchParams.get("year"),
51    sort: parseSort(url.searchParams.get("sort")),
52    page: Number.isFinite(page) && page > 0 ? page : 1,
53  };
54}
55
56/** Middleware: a document route's loader cannot return a raw Response. */
57export const middleware: Route.MiddlewareFunction[] = [
58  async ({ request, context }, next) => {
59    if (!prefersType(request, "application/json")) return next();
60
61    const url = new URL(request.url);
62    const params = readParams(url);
63    const result = await search(getEnv(context), { ...params, pageSize: PAGE_SIZE });
64
65    return new Response(
66      JSON.stringify(
67        {
68          query: result.parsed.raw,
69          parsed: {
70            terms: result.parsed.terms,
71            phrases: result.parsed.phrases,
72            tags: result.parsed.tags,
73            types: result.parsed.types,
74            bases: result.parsed.bases,
75            year: result.parsed.year,
76          },
77          total: result.total,
78          page: result.page,
79          pageSize: result.pageSize,
80          askAvailable: askAvailable(getEnv(context)),
81          truncated: result.truncated,
82          tookMs: result.tookMs,
83          facets: result.facets,
84          results: result.hits.map((hit) => ({
85            url: `${SITE_ORIGIN}${hit.url}`,
86            type: hit.type,
87            title: hit.title,
88            documentTitle: hit.docTitle,
89            anchor: hit.anchor,
90            tags: hit.tags,
91            publishedAt: hit.publishAt ? new Date(hit.publishAt * 1000).toISOString() : null,
92            snippet: hit.snippet,
93            matchedOn: hit.why,
94          })),
95        },
96        null,
97        2,
98      ),
99      {
100        headers: {
101          "content-type": "application/json; charset=utf-8",
102          // Never stored; do not "optimize" this back to a shared cache-control. /search varies on Accept and
103          // Cookie, and once this JSON variant is stored the edge answers cookie-bearing requests from the
104          // cookieless variant, so a `theme=dark` reader gets the light document.
105          "cache-control": NO_STORE_CACHE_CONTROL,
106          vary: "Accept",
107        },
108      },
109    );
110  },
111];
112
113export async function loader({ request, context }: Route.LoaderArgs) {
114  const url = new URL(request.url);
115  const params = readParams(url);
116  const env = getEnv(context);
117
118  const [result, nextPublishAt] = await Promise.all([
119    search(env, { ...params, pageSize: PAGE_SIZE }),
120    nextScheduledPublishAt(env),
121  ]);
122
123  const asked = !result.parsed.isEmpty || hasFilters(result.parsed);
124  const suggestions = asked && result.total === 0 ? await zeroState(env, result.parsed) : null;
125
126  /* After the response via `waitUntil`, failure logged: demand signal is worth less than the page rendering. */
127  if (asked && result.total === 0 && !result.parsed.isEmpty) {
128    getExecutionContext(context).waitUntil(
129      recordZeroResult(env, params.q).catch((error: unknown) => {
130        console.error(JSON.stringify({ alert: "zero-result-record-failed", detail: errorMessage(error) }));
131      }),
132    );
133  }
134
135  // The loader that renders classic results must never wait on the AI layer.
136  return data(
137    { params, result, suggestions, askAvailable: askAvailable(env) },
138    { headers: { [EDGE_CACHE_HEADER]: scheduledEdgeCacheControl(new Date(), nextPublishAt) } },
139  );
140}
141
142export function headers({ loaderHeaders }: Route.HeadersArgs) {
143  const headers = new Headers({
144    // `Accept` stays: this URL also serves JSON.
145    "Cache-Control": SHARED_CACHE_CONTROL,
146    "Cache-Tag": cacheTags(),
147    Vary: HTML_VARY_ACCEPT,
148  });
149  const edge = loaderHeaders.get(EDGE_CACHE_HEADER);
150  if (edge) headers.set(EDGE_CACHE_HEADER, edge);
151  return headers;
152}
153
154export function meta({ loaderData }: Route.MetaArgs) {
155  const q = loaderData?.params.q;
156  const title = q ? `Search: ${q} | ${SITE.name}` : `Search | ${SITE.name}`;
157  return [
158    ...pageMeta({
159      title,
160      description: `Search the writing and pages on ${SITE.name}'s site.`,
161      path: "/search",
162    }),
163    { name: "robots", content: "noindex, follow" },
164  ];
165}
166
167type SearchParams = ReturnType<typeof readParams>;
168type FacetKey = "type" | "base" | "tag" | "year";
169
170/**
171 * The current search with some parts changed. A change of filter or sort drops the page, since
172 * the old page number means nothing in the new list; only a pager link passes one.
173 */
174function searchHref(
175  params: SearchParams,
176  change: Partial<Pick<SearchParams, FacetKey | "sort" | "page">> = {},
177) {
178  const merged = { ...params, page: 1, ...change };
179  const next = new URLSearchParams();
180  if (merged.q) next.set("q", merged.q);
181  if (merged.type) next.set("type", merged.type);
182  if (merged.base) next.set("base", merged.base);
183  if (merged.tag) next.set("tag", merged.tag);
184  if (merged.year) next.set("year", merged.year);
185  // Relevance is the absent value: two spellings of the default would be two cache entries of one page.
186  if (merged.sort === "date") next.set("sort", "date");
187  if (merged.page > 1) next.set("page", String(merged.page));
188  return `/search?${next.toString()}`;
189}
190
191/** A filter in force, as a chip whose link is the same search without it. */
192function ActiveFilterChip({ params, facet, label }: { params: SearchParams; facet: FacetKey; label: string }) {
193  return (
194    <li>
195      <Link to={searchHref(params, { [facet]: null })} className="search-chip is-active">
196        {label} <span aria-hidden="true">x</span>
197        <span className="sr-only">remove filter</span>
198      </Link>
199    </li>
200  );
201}
202
203/** One facet's choices, each a link narrowing the search to it, with its count. */
204function FacetSection({
205  params,
206  facet,
207  heading,
208  values,
209  floor,
210}: {
211  params: SearchParams;
212  facet: FacetKey;
213  heading: string;
214  values: Array<{ value: string | number; label?: string; count: number }>;
215  floor: string;
216}) {
217  return (
218    <section>
219      <h2>{heading}</h2>
220      <ul>
221        {values.map((entry) => (
222          <li key={entry.value}>
223            <Link to={searchHref(params, { [facet]: String(entry.value) })} className="search-chip">
224              {entry.label ?? entry.value} <span className="search-chip-count">{entry.count}{floor}</span>
225            </Link>
226          </li>
227        ))}
228      </ul>
229    </section>
230  );
231}
232
233/** Keyed by the union with no fallback: a reason without a label is a typecheck failure, not a raw value shown to readers. */
234const WHY_LABEL: Record<MatchReason, string> = {
235  title: "title",
236  tag: "tag",
237  body: "body",
238  filter: "filter",
239};
240
241function Result({ hit }: { hit: SearchHit }) {
242  return (
243    <li className="search-result">
244      <div className="search-result-head">
245        <span className="search-type" data-type={hit.type}>
246          {hit.type}
247        </span>
248        <h2 className="search-result-title">
249          <Link to={hit.url}>{hit.title}</Link>
250        </h2>
251      </div>
252
253      {hit.anchor ? (
254        <p className="search-result-context">
255          in <Link to={hit.docUrl}>{hit.docTitle}</Link>
256        </p>
257      ) : null}
258
259      {/* Safe as HTML: the snippet was escaped before its <mark> markers were
260          substituted in. See renderSnippet in search.server.ts. */}
261      <p
262        className="search-snippet"
263        dangerouslySetInnerHTML={{ __html: hit.snippet }}
264      />
265
266      <p className="search-why">
267        matched on{" "}
268        {hit.why.map((reason, i) => (
269          <span key={reason}>
270            {i > 0 ? ", " : ""}
271            <span className="search-why-field">{WHY_LABEL[reason]}</span>
272          </span>
273        ))}
274        {hit.publishAt ? (
275          <>
276            {" "}
277            <span className="search-why-sep">/</span>{" "}
278            <time dateTime={new Date(hit.publishAt * 1000).toISOString()}>
279              {new Date(hit.publishAt * 1000).getUTCFullYear()}
280            </time>
281          </>
282        ) : null}
283      </p>
284    </li>
285  );
286}
287
288/** A search that matched nothing: said plainly, with nearby tags and recent writing to go to instead. */
289function ZeroState({
290  raw,
291  suggestions,
292}: {
293  raw: string;
294  suggestions: NonNullable<Route.ComponentProps["loaderData"]["suggestions"]>;
295}) {
296  return (
297    <div className="search-zero">
298      <p>
299        Nothing matched <strong>{raw}</strong>.
300      </p>
301      {suggestions.nearestTags.length > 0 ? (
302        <section>
303          <h2>Related tags</h2>
304          <ul className="search-chip-row">
305            {suggestions.nearestTags.map((tag) => (
306              <li key={tag}>
307                <Link to={`/search?tag=${encodeURIComponent(tag)}`} className="search-chip">
308                  {tag}
309                </Link>
310              </li>
311            ))}
312          </ul>
313        </section>
314      ) : null}
315      {suggestions.recentPosts.length > 0 ? (
316        <section>
317          <h2>Recent writing</h2>
318          <ul className="search-recent">
319            {suggestions.recentPosts.map((post) => (
320              <li key={post.url}>
321                <Link to={post.url}>{post.title}</Link>
322              </li>
323            ))}
324          </ul>
325        </section>
326      ) : null}
327    </div>
328  );
329}
330
331/** Previous and next around "Page n of m"; an empty span holds each missing side's place. */
332function Pagination({
333  params,
334  page,
335  pageCount,
336  floor,
337}: {
338  params: SearchParams;
339  page: number;
340  pageCount: number;
341  floor: string;
342}) {
343  return (
344    <nav className="search-pagination" aria-label="Search results pages">
345      {page > 1 ? (
346        <Link rel="prev" to={searchHref(params, { page: page - 1 })}>
347          Previous
348        </Link>
349      ) : (
350        <span aria-hidden="true" />
351      )}
352      <span>
353        Page {page} of {pageCount}
354        {floor}
355      </span>
356      {page < pageCount ? (
357        <Link rel="next" to={searchHref(params, { page: page + 1 })}>
358          Next
359        </Link>
360      ) : (
361        <span aria-hidden="true" />
362      )}
363    </nav>
364  );
365}
366
367export default function SearchPage({ loaderData }: Route.ComponentProps) {
368  const { params, result, suggestions, askAvailable } = loaderData;
369  const { facets } = result;
370  const pageCount = Math.max(1, Math.ceil(result.total / result.pageSize));
371  /* A truncated match set makes every count a floor, so it says so rather than reading as exact. */
372  const floor = result.truncated ? "+" : "";
373  // `isEmpty` means no matchable text, not no request: a bare year or tag is answered by the browse path.
374  const hasQuery = !result.parsed.isEmpty || hasFilters(result.parsed);
375
376  return (
377    <>
378      <SiteHeader />
379      <main className="search-page" id="main" tabIndex={-1}>
380        <h1 className="search-heading">Search</h1>
381
382        <SearchForm defaultValue={params.q}>
383          {params.type ? <input type="hidden" name="type" value={params.type} /> : null}
384          {params.base ? <input type="hidden" name="base" value={params.base} /> : null}
385          {params.tag ? <input type="hidden" name="tag" value={params.tag} /> : null}
386          {params.year ? <input type="hidden" name="year" value={params.year} /> : null}
387          {params.sort === "date" ? <input type="hidden" name="sort" value="date" /> : null}
388          <p className="search-hint">
389            Operators: <code>tag:</code>, <code>type:</code>, <code>base:</code> ({SEARCH_BASES.map((b) => b.id).join(", ")}), a bare year, and
390            &quot;quoted phrases&quot;.
391          </p>
392        </SearchForm>
393
394        {/* Rendered even empty: a live region must exist before its text changes, or the live
395            search's count is never announced. */}
396        <p className="search-count" aria-live="polite">
397          {hasQuery
398            ? `${
399                result.total === 0
400                  ? "No results"
401                  : `${result.total}${result.truncated ? "+" : ""} result${
402                      result.total === 1 ? "" : "s"
403                    }`
404              }${result.parsed.year !== null ? ` from ${result.parsed.year}` : ""}`
405            : null}
406        </p>
407
408        {params.type || params.base || params.tag || params.year ? (
409          <ul className="search-active-filters">
410            {params.type ? (
411              <ActiveFilterChip params={params} facet="type" label={`type: ${params.type}`} />
412            ) : null}
413            {params.base ? (
414              <ActiveFilterChip params={params} facet="base" label={`in: ${baseLabel(params.base.toLowerCase())}`} />
415            ) : null}
416            {params.tag ? (
417              <ActiveFilterChip params={params} facet="tag" label={`tag: ${params.tag}`} />
418            ) : null}
419            {params.year ? <ActiveFilterChip params={params} facet="year" label={params.year} /> : null}
420          </ul>
421        ) : null}
422
423        <Enhance module="search" />
424
425        {askAvailable && (params.q ?? "").trim().length > 0 ? (
426          <AskMount question={params.q ?? ""} />
427        ) : null}
428
429        {/* Only on the text path: the browse path is date-ordered in SQL, because a filter carries no relevance signal. */}
430        {hasQuery && result.total > 1 && !result.parsed.isEmpty ? (
431          <nav className="search-sort" aria-label="Sort results">
432            <span className="search-sort-label" id="search-sort-label">
433              Sort
434            </span>
435            <ul aria-labelledby="search-sort-label">
436              <li>
437                <Link
438                  to={searchHref(params, { sort: "relevance" })}
439                  className="search-chip"
440                  aria-current={params.sort === "relevance" ? "true" : undefined}
441                >
442                  Relevance
443                </Link>
444              </li>
445              <li>
446                <Link
447                  to={searchHref(params, { sort: "date" })}
448                  className="search-chip"
449                  aria-current={params.sort === "date" ? "true" : undefined}
450                >
451                  Newest
452                </Link>
453              </li>
454            </ul>
455          </nav>
456        ) : null}
457
458        {/* The body is always there, empty without results, so the live search has a place to
459            write its results on a page that opened with none. */}
460        <div className="search-body">
461          {hasQuery && result.total > 0 ? (
462            <ol className="search-results">
463              {result.hits.map((hit) => (
464                <Result key={hit.uid} hit={hit} />
465              ))}
466            </ol>
467          ) : null}
468
469          {hasQuery && result.total > 0 ? (
470            <aside className="search-facets" aria-label="Filter results">
471              {facets.types.length > 1 ? (
472                <FacetSection params={params} facet="type" heading="Type" values={facets.types} floor={floor} />
473              ) : null}
474
475              {/* One search across the knowledge bases (docs/KNOWLEDGE-BASE.md, A2); each library keeps its own facets. */}
476              {facets.bases.length > 1 ? (
477                <FacetSection params={params} facet="base" heading="Knowledge base" values={facets.bases} floor={floor} />
478              ) : null}
479
480              {facets.tags.length > 0 ? (
481                <FacetSection params={params} facet="tag" heading="Tag" values={facets.tags} floor={floor} />
482              ) : null}
483
484              {facets.years.length > 0 ? (
485                <FacetSection params={params} facet="year" heading="Year" values={facets.years} floor={floor} />
486              ) : null}
487            </aside>
488          ) : null}
489        </div>
490
491        {hasQuery && result.total === 0 && suggestions ? (
492          <ZeroState raw={result.parsed.raw} suggestions={suggestions} />
493        ) : null}
494
495        {pageCount > 1 ? (
496          <Pagination params={params} page={result.page} pageCount={pageCount} floor={floor} />
497        ) : null}
498      </main>
499      <ShellFooter />
500    </>
501  );
502}