Client-Side Instant Search

Technical Deep Dive & Specifications

2.1 The ARIA 1.2 Combobox Architecture

The W3C WAI-ARIA Combobox pattern governs autocomplete search inputs. It consists of an input field linked to a popup listbox:

+-----------------------------------------------------------------------------------------+
| <dialog id="search-palette">                                                            |
|                                                                                         |
|   <div class="combobox-wrapper">                                                        |
|     <input type="search"                                                                |
|            role="combobox"                                                              |
|            aria-expanded="true"                                                         |
|            aria-haspopup="listbox"                                                      |
|            aria-controls="search-results-list"                                          |
|            aria-autocomplete="list"                                                     |
|            aria-activedescendant="opt-2"  <-----+                                       |
|            placeholder="Search docs, APIs, and guides...">                              |
|   </div>                                        |                                       |
|                                                 | (Virtually controls active highlight) |
|   <ul id="search-results-list"                  |                                       |
|       role="listbox"                            |                                       |
|       aria-label="Search Results">              |                                       |
|                                                 |                                       |
|     <li id="opt-1" role="option" aria-selected="false">                                 |
|       <span class="badge">Guide</span> Getting Started with Semantic HTML5              |
|     </li>                                                                               |
|                                                                                         |
|     <li id="opt-2" role="option" aria-selected="true" class="is-selected"> <------------+
|       <span class="badge">API</span> Iframe Sandbox Security Model                      |
|     </li>                                                                               |
|                                                                                         |
|     <li id="opt-3" role="option" aria-selected="false">                                 |
|       <span class="badge">Tutorial</span> Accessible Theme Switcher                     |
|     </li>                                                                               |
|   </ul>                                                                                 |
|                                                                                         |
|   <!-- ARIA Live Region for Screen Reader Count Announcements -->                       |
|   <div id="search-count" role="status" aria-live="polite" class="sr-only">              |
|     3 results available. Use up and down arrows to navigate.                            |
|   </div>                                                                                |
|                                                                                         |
| </dialog>                                                                               |
+-----------------------------------------------------------------------------------------+

2.2 Why aria-activedescendant Over DOM Focus Roving?

When building search dropdowns, developers frequently make the mistake of shifting actual DOM focus (element.focus()) to the <li> results. This causes major issues:

• The user cannot continue typing without refocusing the <input>.
• Mobile software keyboards dismiss and reappear.
• Selection text and caret positions in the input field are lost.

aria-activedescendant solves this perfectly:

1. Physical DOM focus remains locked inside the <input> element at all times.
2. When the user presses ArrowDown or ArrowUp, JavaScript updates the aria-activedescendant attribute to the ID of the highlighted <li> (e.g. aria-activedescendant="opt-2").
3. Assistive technologies read the active option text immediately, exactly as if the option had DOM focus, while the user continues typing uninterrupted.

2.3 Sub-Millisecond Inverted Indexing Algorithm

Rather than running expensive String.includes() on every keystroke across entire documents, we build a tokenized mini-search index:

// Pre-indexed documentation entries
const searchIndex = [
  { id: '1', title: 'Semantic Scaffolding', section: 'Layout', url: '/layout', tokens: ['semantic', 'scaffolding', 'header', 'nav', 'main', 'landmarks'] },
  { id: '2', title: 'Iframe Sandboxing', section: 'Security', url: '/security', tokens: ['iframe', 'sandbox', 'security', 'allow-scripts', 'postmessage'] },
  { id: '3', title: 'Theme Switcher', section: 'CSS', url: '/theme', tokens: ['theme', 'dark', 'light', 'switcher', 'prefers-color-scheme', 'css'] }
];

function search(query) {
  const cleanQuery = query.toLowerCase().trim();
  if (!cleanQuery) return [];
  
  return searchIndex.filter(doc => 
    doc.title.toLowerCase().includes(cleanQuery) ||
    doc.tokens.some(t => t.includes(cleanQuery))
  );
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 105–109: <button id="open-search-btn" aria-haspopup="dialog"> visually invites the user and informs assistive technology of the modal dialog relationship.
• Line 112: <dialog id="search-dialog"> utilizes the HTML5 <dialog> element rendered in the browser's native Top Layer.
• Lines 114–124: <input role="combobox" aria-haspopup="listbox" aria-autocomplete="list"> implements the full ARIA 1.2 Combobox specification.
• Lines 126–128: <ul id="results-listbox" role="listbox"> receives dynamically populated <li role="option"> items.
• Lines 164–170: Global key accelerator intercepts Cmd+K (Mac) or Ctrl+K (Windows/Linux) via (e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k'.
• Lines 172–175: Backdrop click detection closes the modal when users click outside the dialog frame.
• Lines 177–208: renderResults() dynamically renders matching options, maintains aria-activedescendant, and feeds the aria-live announcer.
• Lines 223–238: Keydown handler manages keyboard roving (ArrowDown, ArrowUp, Enter) while preserving text input focus.

Expected Browser Render Output

+--------------------------------------------------------------------------+
| 🔍 [ sandbox                                                           ] |
+--------------------------------------------------------------------------+
| [✓] Sandboxed Iframe Execution                                [Security] |
|     Accessible Theme Switcher                                 [Styling]  |
|                                                                          |
| (Press Enter to jump to section, Esc to dismiss)                         |
+--------------------------------------------------------------------------+