vdoc: implement advanced search (beta) (#7630)

cmd/tools/vdoc/resources/doc.css

@@ -17,6 +17,11 @@
 	--menu-toggle-icon-hover-color: #00000044;
 	--menu-search-background-color: #00000044;
 	--menu-search-font-color: #fff;
+	--menu-search-result-background-hover-color: #00000021;
+	--menu-search-separator-color: #00000044;
+	--menu-search-title-text-color: #d5efff;
+	--menu-search-badge-background-color: #00000044;
+	--menu-search-badge-background-hover-color: #0000004d;
 	--toc-text-color: #2779bd;
 	--toc-indicator-color: #4299e1;
 	--code-default-text-color: #5c6e74;
@@ -49,11 +54,15 @@
 	--menu-background-color: #2d3748;
 	--menu-text-color: #fff;
 	--menu-indent-line-color: #4a5568;
-	--menu-indent-line-active-color: #90cdf4;
+	--menu-indent-line-active-color: #90cdf4; /*#4a5568*/
 	--menu-scrollbar-color: #4a5568;
 	--menu-toggle-icon-color: #fff;
 	--menu-search-background-color: #4a5568;
 	--menu-search-font-color: #fff;
+	--menu-search-separator-color: #4a5568;
+	--menu-search-title-text-color: #90cdf4;
+	--menu-search-badge-background-color: #4a5568;
+	--menu-search-badge-background-hover-color: #4a5568;
 	--toc-text-color: #90cdf4;
 	--toc-indicator-color: #4299e1;
 	--code-default-text-color: #cbd5e0;
@@ -111,7 +120,7 @@ body {
 	scrollbar-width: thin;
 	scrollbar-color: #a0aec0 transparent;
 	scrollbar-color: var(--menu-scrollbar-color) transparent;
-	font-family: 'Work Sans', sans-serif;
+	font-family: "Work Sans", sans-serif;
 }
 *::-webkit-scrollbar {
 	width: 4px;
@@ -125,7 +134,7 @@ body {
 	background-color: var(--menu-scrollbar-color);
 	border: 3px solid transparent;
 }
-.doc-nav li {
+.doc-nav .content li {
 	line-height: 1.8;
 }
 .doc-nav .content.show {
@@ -245,7 +254,7 @@ body {
 }
 .doc-nav > .content > ul > li > ul > li.active {
 	border-color: #00000066;
-	border-color: var(--menu-indent-line-active-color);
+	border-color: var(--menu-search-result-hover-background-color);
 }
 .doc-nav > .content a {
 	color: #fff;
@@ -256,6 +265,69 @@ body {
 .doc-nav > .content a:hover {
 	text-decoration: underline;
 }
+.doc-nav .search {
+	display: none;
+}
+.doc-nav .search li {
+	line-height: 1.5;
+}
+.doc-nav > .search .result:hover {
+	background-color: #00000021;
+	background-color: var(--menu-search-result-background-hover-color);
+}
+.doc-nav > .search .result:hover > .link > .definition > .badge {
+	background-color: #0000004d;
+	background-color: var(--menu-search-badge-background-hover-color);
+}
+.doc-nav > .search .result > .link {
+	padding: 0.5rem 1.4rem;
+	text-decoration: none;
+	color: #fff;
+	color: var(--menu-text-color);
+	display: block;
+}
+.doc-nav > .search .result > .link > .definition {
+	display: flex;
+}
+.doc-nav > .search .result > .link > .definition > .title {
+	color: #90cdf4;
+	color: var(--menu-search-title-text-color);
+	font-size: 0.875rem;
+	font-weight: 500;
+	overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+}
+.doc-nav > .search .result > .link > .definition > .badge {
+	font-size: 0.75rem;
+	display: inline-flex;
+	padding: 0 0.5rem;
+	background-color: #00000044;
+	background-color: var(--menu-search-badge-background-color);
+	margin-left: auto;
+	align-items: center;
+	border-radius: 9999px;
+	font-weight: 500;
+}
+.doc-nav > .search .result > .link > .description {
+	font-family: Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+	font-size: 0.75rem;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+	margin-top: 0.25rem;
+}
+.doc-nav > .search > hr.separator {
+	margin: 0.5rem 0;
+	border-color: #00000044;
+	border-color: var(--menu-search-separator-color);
+	box-sizing: content-box;
+	height: 0;
+	border-width: 0;
+	border-top-width: 1px;
+	border-style: solid;
+    overflow: visible;
+}
 
 /* Main content */
 .doc-scrollview {
@@ -305,7 +377,7 @@ body {
 }
 .doc-content > .doc-node > .title {
 	display: flex;
-	font-family: 'Work Sans', sans-serif;
+	font-family: "Work Sans", sans-serif;
 	font-weight: 500;
 	padding: 0.3rem;
 	align-items: center;
@@ -391,7 +463,7 @@ body {
 	box-sizing: border-box;
 	-ms-overflow-style: none;
 	scrollbar-width: none;
-	font-family: 'Work Sans', sans-serif;
+	font-family: "Work Sans", sans-serif;
 }
 .doc-toc::-webkit-scrollbar {
 	display: none;

cmd/tools/vdoc/resources/doc.js

@@ -80,29 +80,114 @@ function setupDarkMode() {
 
 function setupSearch() {
     var searchInput = document.getElementById('search');
-    searchInput.addEventListener('input', function(e) {
+    var onInputChange = debounce(function(e) {
         var searchValue = e.target.value.toLowerCase();
-        var menuItems = document.querySelectorAll('.content > ul > li');
+        var menu = document.querySelector('.doc-nav > .content');
-        for (var i = 0; i < menuItems.length; i++) {
+        var search = document.querySelector('.doc-nav > .search');
-            var menuItem = menuItems[i];
+        if (searchValue === '') {
-            var links = menuItem.querySelectorAll('a');
+            // reset to default
-            var hasResult = false;
+            menu.style.display = '';
-            for (var li = 0; li < links.length; li++) {
+            search.style.display = '';
-                var link = links[li];
+        } else if (searchValue.length > 2) {
-                if (!searchValue || link.text.toLowerCase().indexOf(searchValue) !== -1) {
+            // search for less than 3 characters can display too much results
-                    hasResult = true;
+            search.innerHTML = '';
+            menu.style.display = 'none';
+            search.style.display = 'block';
+            // cache length for performance
+            var foundModule = false;
+            var searchModuleIndexLength = searchModuleIndex.length;
+            var ul = document.createElement('ul');
+            search.appendChild(ul);
+            for (var i = 0; i < searchModuleIndexLength; i++) {
+                // no toLowerCase needed because modules are always lowercase
+                var title = searchModuleIndex[i];
+                if (title.indexOf(searchValue) === -1) {
+                    continue
                 }
-                if (li > 0) {
+                foundModule = true;
-                    if (!searchValue || link.text.toLowerCase().indexOf(searchValue) !== -1) {
+                // [description, link]
-                        link.style.display = '';
+                var data = searchModuleData[i];
-                    } else {
+                var description = data[0];
-                        link.style.display = 'none';
+                var link = data[1];
+                var el = createSearchResult({
+                    link: link,
+                    title: title,
+                    description: description,
+                    badge: 'module',
+                });
+                ul.appendChild(el);
             }
+            if (foundModule) {
+                var hr = document.createElement('hr');
+                hr.classList.add('separator');
+                search.appendChild(hr);
             }
+            var searchIndexLength = searchIndex.length;
+            var results = [];
+            for (var i = 0; i < searchIndexLength; i++) {
+                var title = searchIndex[i].toLowerCase();
+                if (title.indexOf(searchValue) === -1) {
+                    continue
+                }
+                // [badge, description, link]
+                var data = searchData[i];
+                var badge = data[0];
+                var description = data[1];
+                var link = data[2];
+                var prefix = data[3];
+                results.push({
+                    badge: badge,
+                    description: description,
+                    link: link,
+                    title: prefix + ' ' + title,
+                });
+            }
+            results.sort(function(a, b) {
+                if (a.title < b.title) {
+                    return -1;
+                }
+                if (a.title > b.title) {
+                    return 1;
+                }
+                return 0;
+            });
+            var ul = document.createElement('ul');
+            search.appendChild(ul);
+            for (var i = 0; i < results.length; i++) {
+                var result = results[i];
+                var el = createSearchResult(result);
+                ul.appendChild(el);
             }
-            menuItem.style.display = !searchValue || hasResult ? '' : 'none';
         }
     });
+    searchInput.addEventListener('input', onInputChange);
+}
+
+function createSearchResult(data) {
+    var li = document.createElement('li');
+    li.classList.add('result');
+    var a = document.createElement('a');
+    a.href = data.link;
+    a.classList.add('link');
+    li.appendChild(a);
+    var defintion = document.createElement('div');
+    defintion.classList.add('definition');
+    a.appendChild(defintion);
+    if (data.description) {
+        var description = document.createElement('div');
+        description.classList.add('description');
+        description.textContent = data.description;
+        a.appendChild(description);
+    }
+    var title = document.createElement('span');
+    title.classList.add('title');
+    title.textContent = data.title;
+    defintion.appendChild(title);
+    var badge = document.createElement('badge');
+    badge.classList.add('badge');
+    badge.textContent = data.badge;
+    defintion.appendChild(badge);
+    return li;
 }
 
 function setupCollapse() {
@@ -115,3 +200,14 @@ function setupCollapse() {
         });
     }
 }
+
+function debounce(func, timeout) {
+    var timer;
+    return (...args) => {
+        const next = () => func(...args);
+        if (timer) {
+            clearTimeout(timer);
+        }
+        timer = setTimeout(next, timeout > 0 ? timeout : 300);
+    }
+}

cmd/tools/vdoc/vdoc.v

@@ -66,7 +66,7 @@ const (
 			<header class="doc-nav hidden">
 				<div class="heading-container">
 					<div class="heading">
-						<input type="text" id="search" placeholder="Search...">
+						<input type="text" id="search" placeholder="Search... (beta)" autocomplete="off">
 						<div class="module">{{ head_name }}</div>
 						<div class="toggle-version-container">
 							<span>{{ version }}</span>
@@ -75,6 +75,7 @@ const (
 						{{ menu_icon }}
 					</div>
 				</div>
+				<nav class="search"></nav>
 				<nav class="content hidden">
 					<ul>
 						{{ toc_links }}
@@ -94,6 +95,7 @@ const (
 			</div>
 		</div>
 		{{ footer_assets }}
+		<script async src="search_index.js" type="text/javascript"></script>
 	</body>
 	</html>
 	'
@@ -131,6 +133,22 @@ mut:
 	docs                []doc.Doc
 	manifest            vmod.Manifest
 	assets              map[string]string
+	search_index        []string
+	search_data         []SearchResult
+	search_module_index []string // search results are split into a module part and the rest
+	search_module_data  []SearchModuleResult
+}
+
+struct SearchModuleResult {
+	description string
+	link        string
+}
+
+struct SearchResult {
+	prefix      string
+	badge       string
+	description string
+	link        string
 }
 
 struct ParallelDoc {
@@ -385,17 +403,8 @@ fn doc_node_html(dd doc.DocNode, link string, head bool, tb &table.Table) string
 	md_content := markdown.to_html(dd.comment)
 	hlighted_code := html_highlight(dd.content, tb)
 	node_class := if dd.kind == .const_group { ' const' } else { '' }
-	sym_name := if dd.parent_name.len > 0 && dd.parent_name != 'void' {
+	sym_name := get_sym_name(dd)
-		'($dd.parent_name) $dd.name'
+	node_id := get_node_id(dd)
-	} else {
-		dd.name
-	}
-	tag := if dd.parent_name.len > 0 && dd.parent_name != 'void' {
-		'${dd.parent_name}.$dd.name'
-	} else {
-		dd.name
-	}
-	node_id := slug(tag)
 	hash_link := if !head { ' <a href="#$node_id">#</a>' } else { '' }
 	dnw.writeln('<section id="$node_id" class="doc-node$node_class">')
 	if dd.name.len > 0 {
@@ -420,6 +429,24 @@ fn doc_node_html(dd doc.DocNode, link string, head bool, tb &table.Table) string
 	return dnw_str
 }
 
+fn get_sym_name(dn doc.DocNode) string {
+	sym_name := if dn.parent_name.len > 0 && dn.parent_name != 'void' {
+		'($dn.parent_name) $dn.name'
+	} else {
+		dn.name
+	}
+	return sym_name
+}
+
+fn get_node_id(dn doc.DocNode) string {
+	tag := if dn.parent_name.len > 0 && dn.parent_name != 'void' {
+		'${dn.parent_name}.$dn.name'
+	} else {
+		dn.name
+	}
+	return slug(tag)
+}
+
 fn (cfg DocConfig) readme_idx() int {
 	for i, dc in cfg.docs {
 		if dc.head.name != 'README' {
@@ -624,10 +651,21 @@ fn (cfg DocConfig) gen_footer_text(idx int) string {
 }
 
 fn (cfg DocConfig) render_doc(doc doc.Doc, i int) (string, string) {
+	name := cfg.get_file_name(doc.head.name)
+	output := match cfg.output_type {
+		.html { cfg.gen_html(i) }
+		.markdown { cfg.gen_markdown(i, true) }
+		.json { cfg.gen_json(i) }
+		else { cfg.gen_plaintext(i) }
+	}
+	return name, output
+}
+
+// get_file_name returns the final file name from a module name
+fn (cfg DocConfig) get_file_name(mod string) string {
+	mut name := mod
 	// since builtin is generated first, ignore it
-	mut name := doc.head.name
+	if (cfg.is_vlib && mod == 'builtin' && !cfg.include_readme) || mod == 'README' {
-	if (cfg.is_vlib && doc.head.name == 'builtin' && !cfg.include_readme) ||
-		doc.head.name == 'README' {
 		name = 'index'
 	} else if !cfg.is_multi && !os.is_dir(cfg.output_path) {
 		name = os.file_name(cfg.output_path)
@@ -638,13 +676,7 @@ fn (cfg DocConfig) render_doc(doc doc.Doc, i int) (string, string) {
 		.json { '.json' }
 		else { '.txt' }
 	}
-	output := match cfg.output_type {
+	return name
-		.html { cfg.gen_html(i) }
-		.markdown { cfg.gen_markdown(i, true) }
-		.json { cfg.gen_json(i) }
-		else { cfg.gen_plaintext(i) }
-	}
-	return name, output
 }
 
 fn (cfg DocConfig) work_processor(mut work sync.Channel, mut wg sync.WaitGroup) {
@@ -687,6 +719,82 @@ fn (cfg DocConfig) render() map[string]string {
 	return docs
 }
 
+fn (mut cfg DocConfig) collect_search_index() {
+	if cfg.output_type != .html {
+		return
+	}
+	for doc in cfg.docs {
+		mod := doc.head.name
+		cfg.search_module_index << mod
+		cfg.search_module_data << SearchModuleResult{
+			description: trim_doc_node_description(doc.head.comment)
+			link: cfg.get_file_name(mod)
+		}
+		for _, dn in doc.contents {
+			cfg.create_search_results(mod, dn)
+		}
+	}
+}
+
+fn (mut cfg DocConfig) create_search_results(mod string, dn doc.DocNode) {
+	if dn.kind == .const_group {
+		return
+	}
+	dn_description := trim_doc_node_description(dn.comment)
+	cfg.search_index << dn.name
+	cfg.search_data << SearchResult{
+		prefix: '$dn.kind ($dn.parent_name)'
+		description: dn_description
+		badge: mod
+		link: cfg.get_file_name(mod) + '#' + get_node_id(dn)
+	}
+	for child in dn.children {
+		cfg.create_search_results(mod, child)
+	}
+}
+
+fn trim_doc_node_description(description string) string {
+	mut dn_description := description.replace_each(['\r\n', '\n', '"', '\\"'])
+	// 80 is enough to fill one line
+	if dn_description.len > 80 {
+		dn_description = dn_description[..80]
+	}
+	if '\n' in dn_description {
+		dn_description = dn_description.split('\n')[0]
+	}
+	// if \ is last character, it ends with \" which leads to a JS error
+	if dn_description.ends_with('\\') {
+		dn_description = dn_description.trim_right('\\')
+	}
+	return dn_description
+}
+
+fn (cfg DocConfig) render_search_index() {
+	mut js_search_index := strings.new_builder(200)
+	mut js_search_data := strings.new_builder(200)
+	js_search_index.write('var searchModuleIndex = [')
+	js_search_data.write('var searchModuleData = [')
+	for i, title in cfg.search_module_index {
+		data := cfg.search_module_data[i]
+		js_search_index.write('"$title",')
+		js_search_data.write('["$data.description","$data.link"],')
+	}
+	js_search_index.writeln('];')
+	js_search_index.write('var searchIndex = [')
+	js_search_data.writeln('];')
+	js_search_data.write('var searchData = [')
+	for i, title in cfg.search_index {
+		data := cfg.search_data[i]
+		js_search_index.write('"$title",')
+		// array instead of object to reduce file size
+		js_search_data.write('["$data.badge","$data.description","$data.link","$data.prefix"],')
+	}
+	js_search_index.writeln('];')
+	js_search_data.writeln('];')
+	out_file_path := os.join_path(cfg.output_path, 'search_index.js')
+	os.write_file(out_file_path, js_search_index.str() + js_search_data.str())
+}
+
 fn (mut cfg DocConfig) render_static() {
 	if cfg.output_type != .html {
 		return
@@ -862,6 +970,9 @@ fn (mut cfg DocConfig) generate_docs_from_file() {
 		}
 		cfg.render_static()
 		cfg.render_parallel()
+		println('Creating search index...')
+		cfg.collect_search_index()
+		cfg.render_search_index()
 		// move favicons to target directory
 		println('Copying favicons...')
 		favicons := os.ls(favicons_path) or { panic(err) }