Skip to content

Make docs search respond to arrow keys, and the mobile menu opaque - #195

Merged
fstubner merged 1 commit into
mainfrom
fix/docs-search-keys-and-menu-opacity
Aug 17, 2026
Merged

fstubner merged 1 commit into
mainfrom
fix/docs-search-keys-and-menu-opacity

Conversation

@fstubner

Copy link
Copy Markdown
Owner

The last two findings from the independent 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 — 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's no second notion of "selected" to keep in sync with the rendered list.

Results are re-queried on every keypress — Pagefind re-renders the list as the query changes, so any cached node would be stale by the next keystroke.

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
  • 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; the panel follows the theme.

One sub-finding did not reproduce

The same report noted the first sidebar group label sitting behind the breadcrumb bar. That 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, nothing overlaps.

Verification

astro check clean, build passes, a11y gate 14 routes × both themes 0 violations, file-size guard clean.

Worth noting: the arrow-key behaviour was verified against the deployed build only after a cache-bust — the browser had held stale HTML referencing a previous script hash, which made the fix look like it wasn't working. The CDN was correct throughout.

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.
@fstubner
fstubner merged commit a9a825d into main Aug 17, 2026
14 checks passed
@fstubner
fstubner deleted the fix/docs-search-keys-and-menu-opacity branch August 17, 2026 23:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant