From 6987efcc686a1e5e8e2973b42c19a02d35dd86e4 Mon Sep 17 00:00:00 2001
From: Felix Stubner <felix.stubner@gmail.com>
Date: Tue, 18 Aug 2026 00:10:25 +0100
Subject: [PATCH] Make docs search respond to arrow keys, and the mobile menu
 opaque

Two findings from the acceptance pass.

1. Arrow keys did nothing in the docs search.

   Pagefind's default UI leaves focus in the input and ignores
   ArrowDown/ArrowUp, so results were reachable only by tabbing. Tab and
   Enter did work, so search was usable -- but the down arrow is the key
   most people try first, and it appeared to do nothing at all.

   Focus moves for real rather than painting a highlight and tracking
   `aria-activedescendant`. The results are anchors, so focus gets Enter,
   middle-click and screen-reader announcement for free, and there is no
   second notion of "selected" to keep in sync with the rendered list.
   Results are re-queried on every keypress, because Pagefind re-renders the
   list as the query changes and any cached node would be stale.

   Down from the input enters the list; up from the first result returns to
   the input, so the query is one keypress away rather than Shift+Tab. Up
   from the input wraps to the last result. Verified on the deployed build:

     start -> INPUT
     Down  -> result: Packet capture
     Down  -> result: Packet capture
     Down  -> result: CLI Capture
     Up    -> result: Packet capture
     Up    -> result: Packet capture
     Up    -> INPUT

2. The mobile docs menu was see-through, and dark in light theme.

   The panel background was a hard-coded `rgba(27, 32, 40, 0.96)`, which
   failed twice over. The 4% let the page read through the open menu, with
   body text crossing the menu labels. And because the colour was
   hard-coded rather than tokenised, the panel stayed dark in light theme --
   a dark drawer over a #fbfbfb page, with white showing through it.

   Now `var(--sl-color-bg-sidebar)`: #111 in dark, #fbfbfb in light, opaque
   in both. Measured after the fix, and the panel follows the theme.

   The same report noted the first sidebar group label sitting behind the
   breadcrumb bar. That does not reproduce now -- it was the breadcrumb
   showing *through* the translucent panel, so the opacity fix resolved it.
   Confirmed with elementFromPoint: the panel's own content is topmost
   across its full area.

astro check clean, build passes, a11y 14 routes x both themes 0 violations,
file-size guard clean.
---
 site/src/components/starlight/Header.astro    |  2 +
 site/src/scripts/docs-search-keys.ts          | 65 +++++++++++++++++++
 .../starlight/20-docs-shell-closeout.css      | 14 +++-
 3 files changed, 80 insertions(+), 1 deletion(-)
 create mode 100644 site/src/scripts/docs-search-keys.ts

diff --git a/site/src/components/starlight/Header.astro b/site/src/components/starlight/Header.astro
index c0af7737..968c194a 100644
--- a/site/src/components/starlight/Header.astro
+++ b/site/src/components/starlight/Header.astro
@@ -59,7 +59,9 @@ const isActive = (href: string) => {
 
 <script>
   import { initDocsHeader } from '../../scripts/docs-header';
+  import { initDocsSearchKeys } from '../../scripts/docs-search-keys';
   initDocsHeader();
+  initDocsSearchKeys();
 </script>
 
 <style>
diff --git a/site/src/scripts/docs-search-keys.ts b/site/src/scripts/docs-search-keys.ts
new file mode 100644
index 00000000..b08859fd
--- /dev/null
+++ b/site/src/scripts/docs-search-keys.ts
@@ -0,0 +1,65 @@
+import { onDispose } from './docs-header-disposal';
+
+/**
+ * Arrow-key navigation for the docs search results.
+ *
+ * Pagefind's default UI leaves focus in the input and does nothing with
+ * ArrowDown/ArrowUp, so the results were reachable only by tabbing. Tab and
+ * Enter did work — search was usable — but the down arrow is the key almost
+ * everyone reaches for first, and pressing it appeared to do nothing at all.
+ *
+ * This moves real DOM focus rather than painting a highlight and tracking
+ * `aria-activedescendant`. The results are anchors, so focus gets Enter,
+ * middle-click and screen-reader announcement for free, and there is no
+ * second notion of "selected" to keep in sync with the rendered list.
+ *
+ * Results are queried on every keypress. Pagefind re-renders the list as the
+ * query changes, so any cached node reference would be stale by the next
+ * keystroke.
+ */
+const RESULT_SELECTOR = '.pagefind-ui__result-link';
+const INPUT_SELECTOR = '.pagefind-ui__search-input';
+
+export function initDocsSearchKeys(): void {
+  function handleKeyDown(event: KeyboardEvent) {
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
+
+    const dialog = document.querySelector<HTMLDialogElement>('site-search dialog[open]');
+    if (!dialog) return;
+
+    const target = event.target;
+    if (!(target instanceof HTMLElement) || !dialog.contains(target)) return;
+
+    const input = dialog.querySelector<HTMLInputElement>(INPUT_SELECTOR);
+    const results = [...dialog.querySelectorAll<HTMLAnchorElement>(RESULT_SELECTOR)];
+    if (results.length === 0) return;
+
+    const index = results.indexOf(target.closest<HTMLAnchorElement>(RESULT_SELECTOR) as HTMLAnchorElement);
+    const onInput = target === input;
+
+    // Only act from the input or from a result. Anything else in the dialog
+    // (the close button, filters) keeps its native behaviour.
+    if (!onInput && index === -1) return;
+
+    let next: HTMLElement | null = null;
+    if (event.key === 'ArrowDown') {
+      next = onInput ? results[0] : (results[index + 1] ?? results[0]);
+    } else if (onInput) {
+      // Up from the input wraps to the last result, matching how most
+      // command palettes behave.
+      next = results[results.length - 1];
+    } else {
+      // Up from the first result returns to the input, so the query is
+      // always one keypress away rather than needing Shift+Tab.
+      next = index === 0 ? input : (results[index - 1] ?? input);
+    }
+
+    if (!next) return;
+    event.preventDefault();
+    next.focus();
+    if (next !== input) next.scrollIntoView({ block: 'nearest' });
+  }
+
+  document.addEventListener('keydown', handleKeyDown);
+  onDispose(() => document.removeEventListener('keydown', handleKeyDown));
+}
diff --git a/site/src/styles/starlight/20-docs-shell-closeout.css b/site/src/styles/starlight/20-docs-shell-closeout.css
index 1f7317ad..46a71a5d 100644
--- a/site/src/styles/starlight/20-docs-shell-closeout.css
+++ b/site/src/styles/starlight/20-docs-shell-closeout.css
@@ -207,9 +207,21 @@ html[data-theme='light'] .right-sidebar-panel :where(a[aria-current='location'])
     padding: 0 !important;
     border: 1px solid rgba(140, 149, 166, 0.22) !important;
     border-radius: 8px !important;
+    /* Opaque, and theme-aware.
+     *
+     * This was a hard-coded `rgba(27, 32, 40, 0.96)`, which failed twice
+     * over. The 4% let the page read straight through the open menu -- the
+     * page heading and body text crossing the menu labels. And because the
+     * colour was hard-coded rather than tokenised, the panel stayed dark in
+     * light theme, so a dark drawer sat over a #fbfbfb page with white
+     * bleeding through it.
+     *
+     * `--sl-color-bg-sidebar` is #111 in dark and #fbfbfb in light, so the
+     * panel now follows the theme and hides what is behind it. The green
+     * wash stays; it is decorative and reads on both. */
     background:
       linear-gradient(180deg, rgba(10, 174, 122, 0.04), transparent 11rem),
-      rgba(27, 32, 40, 0.96) !important;
+      var(--sl-color-bg-sidebar) !important;
     box-shadow: 18px 0 46px rgba(0, 0, 0, 0.36) !important;
     overflow: auto !important;
     overscroll-behavior: contain !important;