Merge pull request #12445 from r00ster91/noresults

autodoc: better No Results Found page and other improvements

Author: kristoff-it

lib/docs/index.html

@@ -169,8 +169,8 @@
         width: 100%;
         margin-bottom: 0.8rem;
         padding: 0.5rem;
-        font-size: 1rem;
         font-family: var(--ui);
+        font-size: 1rem;
         color: var(--tx-color);
         background-color: var(--search-bg-color);
         border-top: 0;
@@ -339,8 +339,8 @@
       kbd {
         display: inline-block;
         padding: 0.3em 0.2em;
-        font-size: 1.2em;
-        font-size: var(--mono);
+        font-family: var(--mono);
+        font-size: 1em;
         line-height: 0.8em;
         vertical-align: middle;
         color: #000;
@@ -612,7 +612,7 @@ <h2><span>Zig Version</span></h2>
           </div>
         </nav>
       </div>
-      <div class="flex-right">
+      <div id="docs" class="flex-right">
         <div class="wrap">
           <section class="docs">
             <div style="position: relative">
@@ -654,7 +654,13 @@ <h2>Search Results</h2>
             </div>
             <div id="sectSearchNoResults" class="hidden">
               <h2>No Results Found</h2>
-              <p>Press escape to exit search and then '?' to see more options.</p>
+              <p>Here are some things you can try:</p>
+              <ul>
+                <li>Check out the <a id="langRefLink">Language Reference</a> for the language itself.</li>
+                <li>Check out the <a href="https://ziglang.org/learn/">Learn page</a> for other helpful resources for learning Zig.</li>
+                <li>Use your search engine.</li>
+              </ul>
+              <p>Press <kbd>?</kbd> to see keyboard shortcuts and <kbd>Esc</kbd> to return.</p>
             </div>
             <div id="sectFields" class="hidden">
               <h2>Fields</h2>
@@ -716,11 +722,13 @@ <h2>Tests</h2>
         <div class="modal">
           <h1>Keyboard Shortcuts</h1>
           <dl><dt><kbd>?</kbd></dt><dd>Show this help modal</dd></dl>
-          <dl><dt><kbd>Esc</kbd></dt><dd>Clear focus; close this modal</dd></dl>
           <dl><dt><kbd>s</kbd></dt><dd>Focus the search field</dd></dl>
-          <dl><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd></dl>
-          <dl><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd></dl>
-          <dl><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd></dl>
+          <div style="margin-left: 1em">
+            <dl><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd></dl>
+            <dl><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd></dl>
+            <dl><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd></dl>
+          </div>
+          <dl><dt><kbd>Esc</kbd></dt><dd>Clear focus; close this modal</dd></dl>
         </div>
       </div>
     </div>

lib/docs/main.js

@@ -41,7 +41,7 @@ var zigAnalysis;
   const domSearch = document.getElementById("search");
   const domSectSearchResults = document.getElementById("sectSearchResults");
   const domSectSearchAllResultsLink = document.getElementById("sectSearchAllResultsLink");
-
+  const domDocs = document.getElementById("docs");
   const domListSearchResults = document.getElementById("listSearchResults");
   const domSectSearchNoResults = document.getElementById("sectSearchNoResults");
   const domSectInfo = document.getElementById("sectInfo");
@@ -51,6 +51,7 @@ var zigAnalysis;
   const domHdrName = document.getElementById("hdrName");
   const domHelpModal = document.getElementById("helpModal");
   const domSearchPlaceholder = document.getElementById("searchPlaceholder");
+  const domLangRefLink = document.getElementById("langRefLink");
 
   let searchTimer = null;
   let searchTrimResults = true;
@@ -116,10 +117,10 @@ var zigAnalysis;
   });
   domSectSearchAllResultsLink.addEventListener('click', onClickSearchShowAllResults, false);
   function onClickSearchShowAllResults(ev) {
-      ev.preventDefault();
-      ev.stopPropagation();
-      searchTrimResults = false;
-      onHashChange();
+    ev.preventDefault();
+    ev.stopPropagation();
+    searchTrimResults = false;
+    onHashChange();
   }
 
   domPrivDeclsBox.addEventListener(
@@ -161,6 +162,13 @@ var zigAnalysis;
   window.addEventListener("keydown", onWindowKeyDown, false);
   onHashChange();
 
+  let langRefVersion = zigAnalysis.params.zigVersion;
+  if (!/^\d+\.\d+\.\d+$/.test(langRefVersion)) {
+    // the version is probably not released yet
+    langRefVersion = "master";
+  }
+  domLangRefLink.href = `https://ziglang.org/documentation/${langRefVersion}/`;
+
   function renderTitle() {
     let list = curNav.pkgNames.concat(curNav.declNames);
     let suffix = " - Zig";
@@ -3140,6 +3148,23 @@ var zigAnalysis;
     domSearch.blur();
   }
 
+  // hide the modal if it's visible or return to the previous result page and unfocus the search
+  function onEscape(ev) {
+    if (!domHelpModal.classList.contains("hidden")) {
+      domHelpModal.classList.add("hidden");
+      ev.preventDefault();
+      ev.stopPropagation();
+    } else {
+      domSearch.value = "";
+      domSearch.blur();
+      domSearchPlaceholder.classList.remove("hidden");
+      curSearchIndex = -1;
+      ev.preventDefault();
+      ev.stopPropagation();
+      startSearch();
+    }
+  }
+
   function onSearchKeyDown(ev) {
     switch (getKeyString(ev)) {
       case "Enter":
@@ -3156,19 +3181,15 @@ var zigAnalysis;
         ev.stopPropagation();
         return;
       case "Esc":
-        domSearch.value = "";
-        domSearch.blur();
-        curSearchIndex = -1;
-        ev.preventDefault();
-        ev.stopPropagation();
-        startSearch();
-        return;
+        onEscape(ev);
+        return
       case "Up":
         moveSearchCursor(-1);
         ev.preventDefault();
         ev.stopPropagation();
         return;
       case "Down":
+        // TODO: make the page scroll down if the search cursor is out of the screen
         moveSearchCursor(1);
         ev.preventDefault();
         ev.stopPropagation();
@@ -3237,19 +3258,18 @@ var zigAnalysis;
   function onWindowKeyDown(ev) {
     switch (getKeyString(ev)) {
       case "Esc":
-        if (!domHelpModal.classList.contains("hidden")) {
-          domHelpModal.classList.add("hidden");
+        onEscape(ev);
+        break;
+      case "s":
+        if (domHelpModal.classList.contains("hidden")) {
+          domSearch.focus();
+          domSearch.select();
+          domDocs.scrollTo(0, 0);
           ev.preventDefault();
           ev.stopPropagation();
+          startAsyncSearch();
         }
         break;
-      case "s":
-        domSearch.focus();
-        domSearch.select();
-        ev.preventDefault();
-        ev.stopPropagation();
-        startAsyncSearch();
-        break;
       case "?":
         ev.preventDefault();
         ev.stopPropagation();
@@ -3265,6 +3285,7 @@ var zigAnalysis;
     domHelpModal.style.top =
       window.innerHeight / 2 - domHelpModal.clientHeight / 2 + "px";
     domHelpModal.focus();
+    domSearch.blur();
   }
 
   function clearAsyncSearch() {
@@ -3290,7 +3311,7 @@ var zigAnalysis;
     list.sort();
     return list;
   }
-  
+
   function renderSearch() {
     let matchedItems = [];
     let ignoreCase = curNavSearch.toLowerCase() === curNavSearch;
@@ -3379,13 +3400,13 @@ var zigAnalysis;
         const text = lastPkgName + "." + match.path.declNames.join(".");
         const href = navLink(match.path.pkgNames, match.path.declNames);
 
-        matchedItemsHTML += "<li><a href=\""+ href +"\">"+ text + "</a></li>";
+        matchedItemsHTML += "<li><a href=\"" + href + "\">" + text + "</a></li>";
       }
 
       // Replace the search results using our newly constructed HTML string
       domListSearchResults.innerHTML = matchedItemsHTML;
       if (searchTrimmed) {
-          domSectSearchAllResultsLink.classList.remove("hidden");
+        domSectSearchAllResultsLink.classList.remove("hidden");
       }
       renderSearchCursor();