app/enhance/palette.ts

Functions

Imports

It imports app/enhance/ask.ts. No module of this repo imports it.

Source

1import { escapeHtml } from "@dustinedwards/site-runtime/html";
2
3// ARIA combobox: focus never leaves the input, and arrows move `aria-activedescendant`. Moving DOM
4// focus to each row would break typing.
5
6const RECENT_KEY = "search:recent";
7const RECENT_LIMIT = 5;
8const DEBOUNCE_MS = 140;
9const MIN_QUERY = 2;
10
11const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
12
13interface Hit {
14  url: string;
15  type: string;
16  title: string;
17  documentTitle: string;
18  anchor: string | null;
19  snippet: string;
20  matchedOn: string[];
21}
22
23let dialog: HTMLDialogElement | null = null;
24/** Not named `status`: a module-level `status` collides with `window.status`. */
25let askAvailable = false;
26let askHandle: { cancel(): void } | null = null;
27let askTrigger: HTMLButtonElement | null = null;
28let askLoading = false;
29let askContainer: HTMLDivElement | null = null;
30let input: HTMLInputElement | null = null;
31let listbox: HTMLUListElement | null = null;
32/** Outside the listbox: recent searches are buttons, and a listbox may own only options and groups. */
33let recentList: HTMLDivElement | null = null;
34let statusLine: HTMLParagraphElement | null = null;
35let allResultsLink: HTMLAnchorElement | null = null;
36let hits: Hit[] = [];
37let active = -1;
38let sequence = 0;
39let debounce: ReturnType<typeof setTimeout> | undefined;
40/** The exit fade's length in palette-dialog.css. What is drawn is cleared after it. */
41const EXIT_MS = 120;
42let pendingReset: ReturnType<typeof setTimeout> | undefined;
43
44function readRecent(): string[] {
45  try {
46    const raw = localStorage.getItem(RECENT_KEY);
47    if (!raw) return [];
48    const parsed: unknown = JSON.parse(raw);
49    return Array.isArray(parsed) ? parsed.filter((v): v is string => typeof v === "string") : [];
50  } catch {
51    // A blocked or full localStorage is fine: recent searches are a convenience.
52    return [];
53  }
54}
55
56function pushRecent(query: string) {
57  const trimmed = query.trim();
58  if (!trimmed) return;
59  try {
60    const next = [trimmed, ...readRecent().filter((q) => q !== trimmed)].slice(0, RECENT_LIMIT);
61    localStorage.setItem(RECENT_KEY, JSON.stringify(next));
62  } catch {
63    // Ignored, as above.
64  }
65}
66
67function build() {
68  dialog = document.createElement("dialog");
69  dialog.className = "palette";
70  dialog.setAttribute("aria-label", "Search this site");
71  if (reduceMotion.matches) dialog.dataset.reduceMotion = "";
72
73  dialog.innerHTML = `
74    <form class="palette-form" method="dialog" role="search">
75      <input
76        type="search"
77        class="palette-input"
78        placeholder="Search, or try tag:cloudflare"
79        autocomplete="off"
80        autocapitalize="off"
81        spellcheck="false"
82        role="combobox"
83        aria-expanded="false"
84        aria-controls="palette-listbox"
85        aria-autocomplete="list"
86        aria-label="Search this site"
87      />
88      <button type="button" class="palette-close" aria-label="Close search (Esc)">Esc</button>
89    </form>
90    <p class="palette-status" role="status" aria-live="polite"></p>
91    <ul id="palette-listbox" class="palette-listbox" role="listbox" aria-label="Search results" tabindex="-1"></ul>
92    <div class="palette-recent-list" hidden>
93      <p class="palette-group" id="palette-recent-label">Recent</p>
94      <ul aria-labelledby="palette-recent-label"></ul>
95    </div>
96    <div class="palette-ask">
97      <button type="button" class="palette-ask-trigger" hidden>Ask AI about this</button>
98      <div class="palette-ask-container" hidden></div>
99    </div>
100    <p class="palette-footer">
101      <span><kbd>up</kbd><kbd>down</kbd> to move</span>
102      <span><kbd>Enter</kbd> to open</span>
103      <a href="/search" class="palette-all-results">All results</a>
104    </p>
105  `;
106
107  document.body.appendChild(dialog);
108  input = dialog.querySelector(".palette-input");
109  listbox = dialog.querySelector(".palette-listbox");
110  recentList = dialog.querySelector(".palette-recent-list");
111  statusLine = dialog.querySelector(".palette-status");
112  allResultsLink = dialog.querySelector(".palette-all-results");
113
114  askTrigger = dialog.querySelector(".palette-ask-trigger");
115  askContainer = dialog.querySelector(".palette-ask-container");
116
117  // A deliberate second action: an answer generated on every keystroke would bill Workers AI for typing.
118  askTrigger?.addEventListener("click", () => void runAsk());
119
120  dialog.querySelector(".palette-close")?.addEventListener("click", () => close());
121
122  // The dialog element itself is the click target for backdrop clicks.
123  dialog.addEventListener("click", (event) => {
124    if (event.target === dialog) close();
125  });
126
127  // A backstop, and the path for Escape: `close()` also schedules the reset itself, because the
128  // `close` event proved unreliable for a programmatic close.
129  dialog.addEventListener("close", scheduleReset);
130
131  input?.addEventListener("input", onInput);
132  input?.addEventListener("keydown", onKeydown);
133}
134
135function optionId(i: number) {
136  return `palette-option-${i}`;
137}
138
139function render() {
140  if (!listbox || !input) return;
141  if (dialog && !dialog.open) return;
142  showRecent(false);
143
144  if (hits.length === 0) {
145    listbox.innerHTML = "";
146    input.setAttribute("aria-expanded", "false");
147    input.removeAttribute("aria-activedescendant");
148    return;
149  }
150
151  input.setAttribute("aria-expanded", "true");
152
153  /*
154   * The APG grouped listbox: each type is a `role="group"` named by its label row, so the listbox owns
155   * only groups and options. An option is named by its title alone and described by the rest, since the
156   * snippet made names too long to hear.
157   */
158  const groups = new Map<string, Array<{ hit: Hit; index: number }>>();
159  hits.forEach((hit, index) => {
160    const list = groups.get(hit.type) ?? [];
161    list.push({ hit, index });
162    groups.set(hit.type, list);
163  });
164
165  let html = "";
166  let group = 0;
167  for (const [type, entries] of groups) {
168    const labelId = `palette-group-${group++}`;
169    html += `<li role="group" aria-labelledby="${labelId}"><div class="palette-group" id="${labelId}" role="presentation">${escapeHtml(type)}</div>`;
170    for (const { hit, index } of entries) {
171      const id = optionId(index);
172      const context =
173        hit.anchor && hit.documentTitle !== hit.title
174          ? `<span class="palette-context" id="${id}-context">in ${escapeHtml(hit.documentTitle)}</span>`
175          : "";
176      const described = [context ? `${id}-context` : "", `${id}-snippet`, `${id}-why`]
177        .filter(Boolean)
178        .join(" ");
179      html += `
180        <div
181          id="${id}"
182          class="palette-option"
183          role="option"
184          aria-selected="${index === active}"
185          aria-labelledby="${id}-title"
186          aria-describedby="${described}"
187          data-index="${index}"
188        >
189          <span class="palette-title" id="${id}-title">${escapeHtml(hit.title)}</span>
190          ${context}
191          <span class="palette-snippet" id="${id}-snippet">${hit.snippet}</span>
192          <span class="palette-why" id="${id}-why">${escapeHtml(hit.matchedOn.join(", "))}</span>
193        </div>`;
194    }
195    html += `</li>`;
196  }
197  listbox.innerHTML = html;
198
199  if (active >= 0) {
200    input.setAttribute("aria-activedescendant", optionId(active));
201    listbox
202      .querySelector(`#${CSS.escape(optionId(active))}`)
203      ?.scrollIntoView({ block: "nearest", behavior: reduceMotion.matches ? "auto" : "smooth" });
204  } else {
205    input.removeAttribute("aria-activedescendant");
206  }
207
208  for (const option of listbox.querySelectorAll<HTMLElement>(".palette-option")) {
209    option.addEventListener("mouseenter", () => {
210      active = Number(option.dataset.index ?? -1);
211      syncSelection();
212    });
213    option.addEventListener("click", () => {
214      active = Number(option.dataset.index ?? -1);
215      open_();
216    });
217  }
218}
219
220function syncSelection() {
221  if (!listbox || !input) return;
222  for (const option of listbox.querySelectorAll<HTMLElement>(".palette-option")) {
223    option.setAttribute("aria-selected", String(Number(option.dataset.index) === active));
224  }
225  if (active >= 0) input.setAttribute("aria-activedescendant", optionId(active));
226  else input.removeAttribute("aria-activedescendant");
227}
228
229/** One of the two lists shows at a time, so the empty one never adds its padding above the other. */
230function showRecent(show: boolean) {
231  if (recentList) recentList.hidden = !show;
232  if (listbox) listbox.hidden = show;
233}
234
235function renderRecent() {
236  if (!listbox || !input) return;
237  // Recent searches are not options, so the combobox is not expanded. Set before the early return: a
238  // stale `aria-expanded="true"` over an empty listbox promises options that are not there.
239  input.setAttribute("aria-expanded", "false");
240  input.removeAttribute("aria-activedescendant");
241
242  listbox.innerHTML = "";
243  const recent = readRecent();
244  const list = recentList?.querySelector("ul");
245  if (recent.length === 0 || !list) {
246    showRecent(false);
247    if (statusLine) statusLine.textContent = "";
248    return;
249  }
250  list.innerHTML = recent
251    .map(
252      (query) =>
253        `<li class="palette-recent"><button type="button" data-recent="${escapeHtml(
254          query,
255        )}">${escapeHtml(query)}</button></li>`,
256    )
257    .join("");
258  showRecent(true);
259  for (const button of list.querySelectorAll<HTMLButtonElement>("[data-recent]")) {
260    button.addEventListener("click", () => {
261      if (!input) return;
262      input.value = button.dataset.recent ?? "";
263      onInput();
264      input.focus();
265    });
266  }
267}
268
269async function run(query: string) {
270  const mine = ++sequence;
271  try {
272    const response = await fetch(`/search?q=${encodeURIComponent(query)}`, {
273      headers: { Accept: "application/json" },
274    });
275    if (!response.ok) throw new Error(String(response.status));
276    const data = (await response.json()) as {
277      results?: Hit[];
278      total?: number;
279      askAvailable?: boolean;
280    };
281    if (mine !== sequence) return;
282    askAvailable = data.askAvailable === true;
283    hits = data.results ?? [];
284    active = hits.length > 0 ? 0 : -1;
285    if (statusLine) {
286      statusLine.textContent =
287        hits.length === 0 ? "No results" : `${data.total ?? hits.length} results`;
288    }
289    // Offered even on zero results: a question the keyword index cannot match is where an answer helps.
290    if (askTrigger) askTrigger.hidden = !askAvailable;
291    render();
292  } catch {
293    if (mine !== sequence) return;
294    hits = [];
295    active = -1;
296    if (statusLine) statusLine.textContent = "Search is unavailable. Press Enter for the full page.";
297    render();
298  }
299}
300
301/** A separate dynamic import, so the palette chunk does not carry Ask's weight for readers who only search. */
302async function runAsk() {
303  if (!askContainer || !input) return;
304  const question = input.value.trim();
305  if (!question) return;
306  // The trigger stays visible while the chunk loads, so a second click must not start a second billed answer.
307  if (askLoading) return;
308  askHandle?.cancel();
309  let ask: typeof import("./ask").ask;
310  askLoading = true;
311  try {
312    ({ ask } = await import("./ask"));
313  } catch {
314    // The chunk failed to load: the trigger stays so the reader can retry, and the status says so.
315    if (statusLine) statusLine.textContent = "Ask AI could not load. Try again.";
316    return;
317  } finally {
318    askLoading = false;
319  }
320  askHandle = ask(askContainer, question);
321  /*
322   * The trigger hides only once focus is on the answer panel: hiding it while focused drops focus to
323   * <body>, which inside a modal dialog leaves the reader nowhere (WCAG 2.4.3).
324   */
325  askContainer.querySelector<HTMLElement>(".ask-panel")?.focus();
326  if (askTrigger) askTrigger.hidden = true;
327}
328
329function resetAsk() {
330  askHandle?.cancel();
331  askHandle = null;
332  if (askContainer) {
333    askContainer.textContent = "";
334    askContainer.hidden = true;
335  }
336  if (askTrigger) askTrigger.hidden = true;
337}
338
339function onInput() {
340  if (!input) return;
341  const query = input.value.trim();
342  if (allResultsLink) {
343    allResultsLink.href = query ? `/search?q=${encodeURIComponent(query)}` : "/search";
344  }
345  clearTimeout(debounce);
346  resetAsk();
347
348  if (query.length < MIN_QUERY) {
349    sequence += 1;
350    hits = [];
351    active = -1;
352    renderRecent();
353    return;
354  }
355
356  if (statusLine) statusLine.textContent = "Searching";
357  debounce = setTimeout(() => void run(query), DEBOUNCE_MS);
358}
359
360function open_() {
361  if (!input) return;
362  pushRecent(input.value);
363  const hit = active >= 0 ? hits[active] : undefined;
364  window.location.href = hit ? hit.url : `/search?q=${encodeURIComponent(input.value.trim())}`;
365}
366
367function onKeydown(event: KeyboardEvent) {
368  // Escape first: `<input type="search">` natively clears the field on Escape and stops there, so the
369  // keystroke never reaches the dialog.
370  if (event.key === "Escape") {
371    event.preventDefault();
372    close();
373    return;
374  }
375
376  if (hits.length === 0 && event.key !== "Enter") return;
377
378  if (event.key === "ArrowDown" || event.key === "ArrowUp") {
379    event.preventDefault();
380    if (hits.length === 0) return;
381    const delta = event.key === "ArrowDown" ? 1 : -1;
382    active = (active + delta + hits.length) % hits.length;
383    syncSelection();
384    listbox
385      ?.querySelector(`#${CSS.escape(optionId(active))}`)
386      ?.scrollIntoView({ block: "nearest", behavior: reduceMotion.matches ? "auto" : "smooth" });
387    return;
388  }
389
390  if (event.key === "Home" || event.key === "End") {
391    if (hits.length === 0) return;
392    event.preventDefault();
393    active = event.key === "Home" ? 0 : hits.length - 1;
394    syncSelection();
395    return;
396  }
397
398  if (event.key === "Enter") {
399    event.preventDefault();
400    open_();
401  }
402}
403
404function openPalette() {
405  if (!dialog) build();
406  if (!dialog || dialog.open) return;
407  // Reopened inside the exit fade: clear the last session now, not after it is shown again.
408  if (pendingReset !== undefined) {
409    clearTimeout(pendingReset);
410    pendingReset = undefined;
411    reset();
412  }
413  dialog.showModal();
414  if (input) {
415    input.value = "";
416    input.focus();
417  }
418  // The cleared field must not leave the link carrying the last session's query.
419  if (allResultsLink) allResultsLink.href = "/search";
420  if (statusLine) statusLine.textContent = "";
421  renderRecent();
422}
423
424/**
425 * Bumping the sequence is not optional: a fetch still in flight at close would otherwise resolve
426 * afterwards and repaint the listbox of a closed dialog.
427 */
428function reset() {
429  sequence += 1;
430  hits = [];
431  active = -1;
432  clearTimeout(debounce);
433  resetAsk();
434  if (listbox) listbox.innerHTML = "";
435  showRecent(false);
436  if (statusLine) statusLine.textContent = "";
437  if (input) {
438    input.setAttribute("aria-expanded", "false");
439    input.removeAttribute("aria-activedescendant");
440  }
441}
442
443/**
444 * Stops what is in flight at once (the sequence bump, the debounce, the Ask stream), and clears what
445 * is drawn after the exit fade, so the fade shows what the reader was looking at, not an empty box.
446 * Under reduced motion there is no fade, and the clear is immediate.
447 */
448function scheduleReset() {
449  sequence += 1;
450  clearTimeout(debounce);
451  askHandle?.cancel();
452  askHandle = null;
453  clearTimeout(pendingReset);
454  pendingReset = setTimeout(
455    () => {
456      pendingReset = undefined;
457      if (!dialog?.open) reset();
458    },
459    reduceMotion.matches ? 0 : EXIT_MS,
460  );
461}
462
463function close() {
464  dialog?.close();
465  scheduleReset();
466}
467
468/**
469 * The gestures are bound once, in `theme.ts`, which loads this bundle on first use. A second binding
470 * here would fire too and find the dialog already open.
471 */
472document.addEventListener("palette:open", () => openPalette());