Implement Search as ARIA spec compliant* dialog and combobox pattern

src/lib/internationalization/locales/en.cts

@@ -522,6 +522,6 @@ export = {
     theme_hierarchy_expand: "Expand",
     theme_hierarchy_collapse: "Collapse",
     theme_search_index_not_available: "The search index is not available",
-    theme_search_no_results: "No results found",
+    theme_search_no_results_found_for: "No results found for", // for <search query>
     theme_search_placeholder: "Search the docs",
 } as const;

src/lib/output/plugins/AssetsPlugin.ts

@@ -39,8 +39,8 @@ export class AssetsPlugin extends RendererComponent {
                 this.application.i18n.theme_hierarchy_collapse(),
             theme_search_index_not_available:
                 this.application.i18n.theme_search_index_not_available(),
-            theme_search_no_results:
-                this.application.i18n.theme_search_no_results(),
+            theme_search_no_results_found_for:
+                this.application.i18n.theme_search_no_results_found_for(),
         };
     }
 

src/lib/output/themes/default/assets/typedoc/Application.ts

@@ -9,7 +9,7 @@ declare global {
             hierarchy_expand: string;
             hierarchy_collapse: string;
             theme_search_index_not_available: string;
-            theme_search_no_results: string;
+            theme_search_no_results_found_for: string;
         };
     }
 }
@@ -23,7 +23,7 @@ window.translations ||= {
     hierarchy_expand: "Expand",
     hierarchy_collapse: "Collapse",
     theme_search_index_not_available: "The search index is not available",
-    theme_search_no_results: "No results found",
+    theme_search_no_results_found_for: "No results found for",
 };
 
 /**

src/lib/output/themes/default/assets/typedoc/components/Search.ts

@@ -37,25 +37,23 @@ interface SearchState {
 /** Counter to get unique IDs for options */
 let optionsIdCounter = 0;
 
-let resultCount = 0;
-
 /**
  * Populates search data into `state`, if available.
  * Removes deault loading message
  */
-async function updateIndex(state: SearchState, results: HTMLElement) {
+async function updateIndex(state: SearchState, status: HTMLElement) {
     if (!window.searchData) return;
 
     const data: IData = await decompressJson(window.searchData);
 
     state.data = data;
     state.index = Index.load(data.index);
 
-    results.querySelector("li.state")?.remove();
+    status.innerHTML = "";
 }
 
 export function initSearch() {
-    const searchTrigger = document.getElementById(
+    const trigger = document.getElementById(
         "tsd-search-trigger",
     ) as HTMLButtonElement | null;
 
@@ -73,7 +71,9 @@ export function initSearch() {
         "tsd-search-script",
     ) as HTMLScriptElement | null;
 
-    if (!(searchTrigger && searchEl && field && results && searchScript)) {
+    const status = document.getElementById("tsd-search-status");
+
+    if (!(trigger && searchEl && field && results && searchScript && status)) {
         throw new Error("Search controls missing");
     }
 
@@ -83,37 +83,46 @@ export function initSearch() {
 
     searchScript.addEventListener("error", () => {
         const message = window.translations.theme_search_index_not_available;
-        const stateEl = createStateEl(message);
-        results.replaceChildren(stateEl);
+        updateStatusEl(status, message);
     });
     searchScript.addEventListener("load", () => {
-        updateIndex(state, results);
+        updateIndex(state, status);
     });
-    updateIndex(state, results);
+    updateIndex(state, status);
 
-    bindEvents(searchTrigger, searchEl, results, field, state);
+    bindEvents({ trigger, searchEl, results, field, status }, state);
 }
 
 function bindEvents(
-    trigger: HTMLButtonElement,
-    searchEl: HTMLDialogElement,
-    results: HTMLElement,
-    field: HTMLInputElement,
+    elements: {
+        trigger: HTMLButtonElement;
+        searchEl: HTMLDialogElement;
+        results: HTMLElement;
+        field: HTMLInputElement;
+        status: HTMLElement;
+    },
     state: SearchState,
 ) {
+    const { field, results, searchEl, status, trigger } = elements;
+
     setUpModal(searchEl, "fade-out", { closeOnClick: true });
 
     trigger.addEventListener("click", () => openModal(searchEl));
 
     field.addEventListener(
         "input",
         debounce(() => {
-            updateResults(results, field, state);
+            updateResults(results, field, status, state);
         }, 200),
     );
 
     field.addEventListener("keydown", (e) => {
-        if (resultCount === 0 || e.ctrlKey || e.metaKey || e.altKey) {
+        if (
+            results.childElementCount === 0 ||
+            e.ctrlKey ||
+            e.metaKey ||
+            e.altKey
+        ) {
             return;
         }
 
@@ -169,13 +178,15 @@ function bindEvents(
 function updateResults(
     results: HTMLElement,
     query: HTMLInputElement,
+    status: HTMLElement,
     state: SearchState,
 ) {
     // Don't clear results if loading state is not ready,
     // because loading or error message can be removed.
     if (!state.index || !state.data) return;
 
     results.innerHTML = "";
+    status.innerHTML = "";
     optionsIdCounter += 1;
 
     const searchText = query.value.trim();
@@ -198,11 +209,11 @@ function updateResults(
         res = [];
     }
 
-    resultCount = res.length;
-
-    if (res.length === 0) {
-        const item = createStateEl(window.translations.theme_search_no_results);
-        results.appendChild(item);
+    if (res.length === 0 && searchText) {
+        const message =
+            window.translations.theme_search_no_results_found_for +
+            ` "<strong>${searchText}</strong>"`;
+        updateStatusEl(status, message);
         return;
     }
 
@@ -338,14 +349,11 @@ function escapeHtml(text: string) {
 }
 
 /**
- * Returns a `li` element, with `state` class,
- * @param message Message to set as **innerHTML**
+ * Updates the status element, with aria-live attriute, which should be announced to the user.
+ * @param message Message to set as **innerHTML** in a wrapper element, if not empty.
  */
-function createStateEl(message: string) {
-    const stateEl = document.createElement("li");
-    stateEl.className = "state";
-    stateEl.innerHTML = message;
-    return stateEl;
+function updateStatusEl(status: HTMLElement, message: string) {
+    status.innerHTML = message ? `<div>${message}</div>` : "";
 }
 
 /**

src/lib/output/themes/default/partials/toolbar.tsx

@@ -31,11 +31,13 @@ export const toolbar = (context: DefaultThemeRenderContext, props: PageEvent<Ref
                     autocapitalize="off"
                     autocomplete="off"
                     placeholder={context.i18n.theme_search_placeholder()}
+                    maxLength={100}
                 />
 
-                <ul role="listbox" id="tsd-search-results">
-                    <li class="state">{context.i18n.theme_preparing_search_index()}</li>
-                </ul>
+                <ul role="listbox" id="tsd-search-results"></ul>
+                <div id="tsd-search-status" aria-live="polite" aria-atomic="true">
+                    <div>{context.i18n.theme_preparing_search_index()}</div>
+                </div>
             </dialog>
 
             <a

static/style.css

@@ -1154,51 +1154,57 @@
     }
     #tsd-search-results {
         margin: 0;
-        margin-top: 0.5rem;
         padding: 0;
         list-style: none;
         flex: 1 1 auto;
         display: flex;
         flex-direction: column;
         overflow-y: auto;
     }
-    #tsd-search-results > li[role="option"] {
+    #tsd-search-results:not(:empty) {
+        margin-top: 0.5rem;
+    }
+    #tsd-search-results > li {
         background-color: var(--color-background);
         line-height: 1.5;
         box-sizing: border-box;
         border-radius: 4px;
     }
-    #tsd-search-results > li[role="option"]:nth-child(even) {
+    #tsd-search-results > li:nth-child(even) {
         background-color: var(--color-background-secondary);
     }
-    #tsd-search-results > li[role="option"]:is(:hover, [aria-selected="true"]) {
+    #tsd-search-results > li:is(:hover, [aria-selected="true"]) {
         background-color: var(--color-accent);
     }
     /* It's important that this takes full size of parent `li`, to capture a click on `li` */
-    #tsd-search-results > li[role="option"] > a {
+    #tsd-search-results > li > a {
         display: flex;
         align-items: center;
         padding: 0.5rem 0.25rem;
         box-sizing: border-box;
         width: 100%;
     }
-    #tsd-search-results > li[role="option"] > a > .text {
+    #tsd-search-results > li > a > .text {
         flex: 1 1 auto;
         min-width: 0;
         overflow-wrap: anywhere;
     }
-    #tsd-search-results > li[role="option"] > a .parent {
+    #tsd-search-results > li > a .parent {
         color: var(--color-text-aside);
     }
-    #tsd-search-results > li[role="option"] > a mark {
+    #tsd-search-results > li > a mark {
         color: inherit;
         background-color: inherit;
         font-weight: bold;
     }
-    #tsd-search-results > li.state {
+    #tsd-search-status {
         flex: 1;
         display: grid;
         place-content: center;
+        text-align: center;
+        overflow-wrap: anywhere;
+    }
+    #tsd-search-status:not(:empty) {
         min-height: 6rem;
     }