Commit 4f5082fc86e617b9d51e83c42816716ea4ed98b3 | zig

author	Loris Cro <kappaloris@gmail.com> 2023-07-25 19:19:39+02:00
committer	Loris Cro <kappaloris@gmail.com> 2023-07-25 19:19:39+02:00
log	4f5082fc86e617b9d51e83c42816716ea4ed98b3
tree	65c44b409b34175f9494ddf6b372924995da1880
parent	dc24835168d107183671288899954f5af56b0ba1

autodoc: improve handling of periods in search box and add search explainer

2 files changed, 119 insertions(+), 3 deletions(-)

lib
- docs
  - index.html
  - main.js

lib/docs/index.html+103

...	@@ -27,6 +27,7 @@	...	@@ -27,6 +27,7 @@
27	--search-other-results-color: rgb(100, 100, 100);	27	--search-other-results-color: rgb(100, 100, 100);
28	--modal-sh-color: rgba(0, 0, 0, 0.75);	28	--modal-sh-color: rgba(0, 0, 0, 0.75);
29	--modal-bg-color: #aaa;	29	--modal-bg-color: #aaa;
		30	--warning-popover-bg-color: #ff4747;
30	}	31	}
31		32
32	html, body { margin: 0; padding: 0; height: 100%; }	33	html, body { margin: 0; padding: 0; height: 100%; }
...	@@ -249,6 +250,57 @@	...	@@ -249,6 +250,57 @@
249	top: 5px;	250	top: 5px;
250	left: 5px;	251	left: 5px;
251	}	252	}
		253
		254	#dotsPopover:before {
		255	position: absolute;
		256	content: "";
		257	left: 20px;
		258	top: -8px;
		259	border-style: solid;
		260	border-width: 0 10px 10px 10px;
		261	border-color: transparent transparent var(--warning-popover-bg-color) transparent;
		262	transition-duration: 0.3s;
		263	transition-property: transform;
		264	z-index: 10;
		265	}
		266
		267	#dotsPopover {
		268	position: absolute;
		269	opacity: 0;
		270	visibility: hidden;
		271	background-color: var(--warning-popover-bg-color);
		272	border-radius: 10px;
		273	left: 10px;
		274	transform: translate(0, -20px);
		275	padding: 0.5rem 1rem;
		276	box-shadow: 0 2px 5px 0 rgba(0, 0, 0, 0.26);
		277	transition: all 0.5s cubic-bezier(0.75, -0.02, 0.2, 0.97);
		278	z-index: 20;
		279	}
		280
		281	#dotsPopover.active {
		282	opacity: 1;
		283	visibility: visible;
		284	transform: translate(0, 0);
		285	}
		286
		287	#searchHelp {
		288	}
		289
		290	#searchHelp summary {
		291	color: red;
		292	list-style-position: outside;
		293	}
		294
		295	#searchHelp summary.normal {
		296	color: var(--search-other-results-color);
		297	transition: all 0.5s cubic-bezier(0.75, -0.02, 0.2, 0.97);
		298	}
		299
		300	#searchHelp div {
		301	background-color: var(--modal-bg-color);
		302	padding: 0.5rem 1rem;
		303	}
252		304
253	.other-results {	305	.other-results {
254	line-height: 1em;	306	line-height: 1em;
...	@@ -555,6 +607,7 @@	...	@@ -555,6 +607,7 @@
555	--search-other-results-color: rgba(255, 255, 255, 0.28);	607	--search-other-results-color: rgba(255, 255, 255, 0.28);
556	--modal-sh-color: rgba(142, 142, 142, 0.5);	608	--modal-sh-color: rgba(142, 142, 142, 0.5);
557	--modal-bg-color: #333;	609	--modal-bg-color: #333;
		610	--warning-popover-bg-color: #600000;
558	}	611	}
559		612
560	.docs pre {	613	.docs pre {
...	@@ -892,10 +945,60 @@	...	@@ -892,10 +945,60 @@
892	<div style="position: relative">	945	<div style="position: relative">
893	<span id="searchPlaceholder"><!-- populated by setPrefSlashSearch --></span>	946	<span id="searchPlaceholder"><!-- populated by setPrefSlashSearch --></span>
894	<input type="search" class="search" id="search" autocomplete="off" spellcheck="false" disabled>	947	<input type="search" class="search" id="search" autocomplete="off" spellcheck="false" disabled>
		948	<div id="dotsPopover">
		949	Use spaces instead of dots. See $resource for more info.
		950	</div>
895	</div>	951	</div>
896	</section>	952	</section>
897	</div>	953	</div>
898	<div id="sectSearchResults" class="docs hidden">	954	<div id="sectSearchResults" class="docs hidden">
		955	<details id="searchHelp">
		956	<summary id="searchHelpSummary" class="normal">How to search effectively</summary>
		957	<div>
		958	<h2>How To Search Effectively</h2>
		959	<h3>Matching</h3>
		960	<ul>
		961	<li>Search is case-insensitive by default.</li>
		962	<li>Using uppercase letters in your query will make the search
		963	case-sensitive.</li>
		964	<li>Given <code>ArrayListUnmanaged</code>:
		965	<ul>
		966	<li>the following words will match:
		967	<ul>
		968	<li><code>array</code></li>
		969	<li><code>list</code></li>
		970	<li><code>unmanaged</code></li>
		971	</ul>
		972	</li>
		973	<li>the following words will <b>NOT</b> match:
		974	<ul>
		975	<li><code>stun</code></li>
		976	<li><code>ray</code></li>
		977	<li><code>managed</code></li>
		978	</ul>
		979	</li>
		980	</ul>
		981	</li>
		982	<li>More precisely the search system is based on a Radix Tree. The Radix Tree contains full decl names plus some suffixes, split by following the official style guide (e.g. <code>HashMapUnmanaged</code> also produces <code>MapUnmanaged</code> and <code>Unmanaged</code>, same with snake_case and camelCase names). </li>
		983	</ul>
		984
		985	<h3>Multiple terms</h3>
		986
		987	<ul>
		988	<li>When a search query contains multiple terms, order doesn't matter when
		989	all terms match within a single decl name (e.g. "map auto" will match <code>AutoHashMap</code>).</li>
		990	<li>Query term order does matter when matching different decls alognside
		991	a path (e.g. "js parse" matching <code>std.json.parse</code>), in which
		992	case the order of the terms will determine whether the match goes above or
		993	below the "other results" line.</li>
		994	<li>As an example, "fs create" will put above the line all things related to the creation of files and directories inside of `std.fs`, while still showing (but below the line) matches from `std.Bulild`.</li>
		995	<li>As another example, "fs windows" will prioritize windows-related results in `std.fs`, while "windows fs" will prioritize "fs"-related results in `std.windows`.</li>
		996	<li>This means that if you're searching inside a target namespace, you never have to read below the "other results" line.</li>
		997	<li>Since matching doesn't have to be perfect, you can also target a group of namespaces to search into. For example "array orderedremove" will show you all "Array-" namespaces that support <code>orderedRemove</code>.</li>
		998	<li>Periods are replaced by spaces because the Radix Tree doesn't index full paths, and in practice you should expect the match scoring system to consistently give you what you're looking for even when your query path is split into multiple terms.</li>
		999	</ul>
		1000	</div>
		1001	</details>
899	<h2>Search Results</h2>	1002	<h2>Search Results</h2>
900	<ul id="listSearchResults"></ul>	1003	<ul id="listSearchResults"></ul>
901	<p id="sectSearchAllResultsLink" class="hidden"><a href="">show all results</a></p>	1004	<p id="sectSearchAllResultsLink" class="hidden"><a href="">show all results</a></p>

lib/docs/main.js+16-3

 @@ -54,6 +54,7 @@ const NAV_MODES = {
   const domFnNoExamples = document.getElementById("fnNoExamples");
   const domDeclNoRef = document.getElementById("declNoRef");
   const domSearch = document.getElementById("search");
+  const domSearchHelpSummary = document.getElementById("searchHelpSummary");
   const domSectSearchResults = document.getElementById("sectSearchResults");
   const domSectSearchAllResultsLink = document.getElementById("sectSearchAllResultsLink");
   const domDocs = document.getElementById("docs");
 @@ -3599,8 +3600,22 @@ Happy writing!
     }
   }
+  let domDotsToggleTimeout = null;
   function onSearchInput(ev) {
     curSearchIndex = -1;
+    let replaced = domSearch.value.replaceAll(".", " ");
+    if (replaced != domSearch.value) {
+      domSearch.value = replaced;
+      domSearchHelpSummary.classList.remove("normal");
+      if (domDotsToggleTimeout != null) {
+        clearTimeout(domDotsToggleTimeout);
+        domDotsToggleTimeout = null;
+      }
+      domDotsToggleTimeout = setTimeout(function () {
+        domSearchHelpSummary.classList.add("normal");
+      }, 1000);
+    }
     startAsyncSearch();
   }
 @@ -3752,9 +3767,7 @@ Happy writing!
     clearAsyncSearch();
     let oldHash = location.hash;
     let parts = oldHash.split("?");
-    // TODO: make a tooltip that shows the user that we've replaced their dots
+    let newPart2 = domSearch.value === "" ? "" : "?" + domSearch.value;
-    let box_text = domSearch.value.replaceAll(".", " ");
-    let newPart2 = box_text === "" ? "" : "?" + box_text;
     location.replace(parts.length === 1 ? oldHash + newPart2 : parts[0] + newPart2);
   }
   function getSearchTerms() {