doc,tools: improve navigability of API docs

PR-URL: #41404
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Author: ShogunPanda

doc/api_assets/style.css

@@ -162,7 +162,7 @@ em code {
 margin-bottom:1rem;
 }
 
-#gtocul {
+#gtoc>ul {
 list-style: none;
 margin-left:0;
 line-height:1.5rem;
@@ -172,60 +172,106 @@ em code {
 color:var(--color-critical);
 }
 
-li.version-picker {
+li.picker-header {
 position: relative;
 }
 
-li.version-picker:hover>a {
+li.picker-header .collapsed-arrow,li.picker-header .expanded-arrow {
+width:1.5ch;
+height:1.5em;
+}
+
+li.picker-header .collapsed-arrow {
+display: inline-block;
+}
+
+li.picker-header .expanded-arrow {
+display: none;
+}
+
+li.picker-header:hover .collapsed-arrow {
+display: none;
+}
+
+li.picker-header:hover .expanded-arrow {
+display: inline-block;
+}
+
+li.picker-header:hover>a {
 border-radius:2px2px00;
 }
 
-li.version-picker:hover>ol {
+li.picker-header:hover>.picker {
 display: block;
 z-index:1;
 }
 
-li.version-pickeraspan {
+li.picker-headeraspan {
 font-size:.7rem;
 }
 
-ol.version-picker {
+.picker {
 background-color:var(--color-fill-app);
 border:1px solid var(--color-brand-secondary);
 border-radius:002px2px;
 display: none;
 list-style: none;
 position: absolute;
-right:0;
+left:0;
 top:100%;
-width:100%;
+width: max-content;
+min-width:min(300px,75vw);
+max-width:75vw;
+max-height:min(600px,60vh);
+overflow-y: auto;
 }
 
-#gtocol.version-pickerli {
+.picker>ul, .picker>ol {
+list-style: none;
+margin-left:0;
+line-height:1.5rem;
+}
+
+.pickerli {
 display: block;
 border-right:0;
 margin-right:0;
 }
 
-ol.version-pickerlia {
+.pickerlia {
 border-radius:0;
 display: block;
 margin:0;
 padding:.1rem;
 padding-left:1rem;
 }
 
-ol.version-pickerli:last-childa {
+.pickerlia.active,
+.pickerlia.active:hover,
+.pickerlia.active:focus {
+font-weight:700;
+}
+
+.pickerli:last-childa {
 border-bottom-right-radius:1px;
 border-bottom-left-radius:1px;
 }
 
+.gtoc-picker-header {
+display: none;
+}
+
 .line {
 width:calc(100%-1rem);
 display: block;
 padding-bottom:1px;
 }
 
+.picker .line {
+margin:0;
+width:100%;
+}
+
 .api_stability {
 color:var(--white) !important;
 margin:001rem;
@@ -506,6 +552,41 @@ hr {
 margin-top:.666rem;
 }
 
+.tocul {
+margin:0
+}
+
+.toclia::before {
+content:"■";
+color:var(--color-text-primary);
+padding-right:1em;
+font-size:0.9em;
+}
+
+.toclia:hover::before {
+color:var(--white);
+}
+
+.toculula {
+padding-left:1rem;
+}
+
+.tocululula {
+padding-left:2rem;
+}
+
+.toculululula {
+padding-left:3rem;
+}
+
+.tocululululula {
+padding-left:4rem;
+}
+
+.toculululululula {
+padding-left:5rem;
+}
+
 #toc .stability_0::after {
 background-color:var(--red2);
 color:var(--white);
@@ -718,10 +799,25 @@ kbd {
  }
 }
 
+.header {
+position: sticky;
+top:-1px;
+z-index:1;
+padding-top:1rem;
+background-color:var(--color-fill-app);
+}
+
+@medianot screen, (max-height:1000px) {
+ .header {
+position: relative;
+top:0;
+ }
+}
+
 .header-container {
 display: flex;
 align-items: center;
-margin:1.5rem01rem;
+margin-bottom:1rem;
 justify-content: space-between;
 }
 
@@ -735,7 +831,7 @@ kbd {
 outline:var(--brand3) dotted 2px;
 }
 
-@mediaonly screen and (min-width:577px) {
+@mediaonly screen and (min-width:601px) {
 #gtoc>ul>li {
 display: inline;
 border-right:1px currentColor solid;
@@ -748,6 +844,10 @@ kbd {
 margin-right:0;
 padding-right:0;
  }
+
+#gtoc>ul>li.gtoc-picker-header {
+display: none;
+ }
 }
 
 @mediaonly screen and (max-width:1024px) {
@@ -764,6 +864,10 @@ kbd {
 #column2 {
 display: none;
  }
+
+#gtoc>ul>li.gtoc-picker-header {
+display: inline;
+ }
 }
 
 .icon {

doc/template.html

@@ -22,7 +22,7 @@
 </div>
 
 <divid="column1" data-id="__ID__" class="interior">
-<header>
+<headerclass="header">
 <divclass="header-container">
 <h1>Node.js __VERSION__ documentation</h1>
 <buttonclass="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden>
@@ -39,17 +39,27 @@ <h1>Node.js __VERSION__ documentation</h1>
 </div>
 <divid="gtoc">
 <ul>
-<li>
-<ahref="index.html">Index</a>
-</li>
-<li>
-<ahref="all.html">View on single page</a>
-</li>
-<li>
-<ahref="__FILENAME__.json">View as JSON</a>
-</li>
+ __TOC_PICKER__
+ __GTOC_PICKER__
  __ALTDOCS__
- __EDIT_ON_GITHUB__
+<liclass="picker-header">
+<ahref="#">
+<spanclass="collapsed-arrow">&#x25ba;</span><spanclass="expanded-arrow">&#x25bc;</span>
+ Options
+</a>
+
+<divclass="picker">
+<ul>
+<li>
+<ahref="all.html">View on single page</a>
+</li>
+<li>
+<ahref="__FILENAME__.json">View as JSON</a>
+</li>
+ __EDIT_ON_GITHUB__ 
+</ul>
+</div>
+</li>
 </ul>
 </div>
 <hr>

test/doctool/test-make-doc.mjs

@@ -40,7 +40,8 @@ const links = toc.match(globalRe);
 assert.notStrictEqual(links,null);
 
 // Filter out duplicate links, leave just filenames, add expected JSON files.
-constlinkedHtmls=[...newSet(links)].map((link)=>link.match(re)[1]);
+constlinkedHtmls=[...newSet(links)].map((link)=>link.match(re)[1])
+.concat(['index.html']);
 constexpectedJsons=linkedHtmls
 .map((name)=>name.replace('.html','.json'));
 constexpectedDocs=linkedHtmls.concat(expectedJsons);

tools/doc/html.mjs

@@ -98,8 +98,10 @@ export function toHTML({ input, content, filename, nodeVersion, versions }) {
 .replace(/__FILENAME__/g,filename)
 .replace('__SECTION__',content.section)
 .replace(/__VERSION__/g,nodeVersion)
-.replace('__TOC__',content.toc)
-.replace('__GTOC__',gtocHTML.replace(
+.replace(/__TOC__/g,content.toc)
+.replace(/__TOC_PICKER__/g,tocPicker(id,content))
+.replace(/__GTOC_PICKER__/g,gtocPicker(id))
+.replace(/__GTOC__/g,gtocHTML.replace(
 `class="nav-${id}"`,`class="nav-${id} active"`))
 .replace('__EDIT_ON_GITHUB__',editOnGitHub(filename))
 .replace('__CONTENT__',processContent(content));
@@ -442,17 +444,18 @@ export function buildToc({ filename, apilinks }) {
 });
 
 if(toc!==''){
-file.toc='<details id="toc" open><summary>Table of contents</summary>'+
-unified()
-.use(markdown)
-.use(gfm)
-.use(remark2rehype,{allowDangerousHtml: true})
-.use(raw)
-.use(htmlStringify)
-.processSync(toc).toString()+
-'</details>';
+constinner=unified()
+.use(markdown)
+.use(gfm)
+.use(remark2rehype,{allowDangerousHtml: true})
+.use(raw)
+.use(htmlStringify)
+.processSync(toc).toString();
+
+file.toc=`<details id="toc" open><summary>Table of contents</summary>${inner}</details>`;
+file.tocPicker=`<div class="toc">${inner}</div>`;
 }else{
-file.toc='<!-- TOC -->';
+file.toc=file.tocPicker='<!-- TOC -->';
 }
 };
 }
@@ -508,13 +511,60 @@ function altDocs(filename, docCreated, versions) {
 constlist=versions.filter(isDocInVersion).map(wrapInListItem).join('\n');
 
 returnlist ? `
- <li class="version-picker">
- <a href="#">View another version <span>&#x25bc;</span></a>
- <ol class="version-picker">${list}</ol>
+ <li class="picker-header">
+ <a href="#">
+ <span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
+ Other versions
+ </a>
+ <div class="picker"><ol id="alt-docs">${list}</ol></div>
  </li>
  ` : '';
 }
 
 functioneditOnGitHub(filename){
 return`<li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/${filename}.md">Edit on GitHub</a></li>`;
 }
+
+functiongtocPicker(id){
+if(id==='index'){
+return'';
+}
+
+// Highlight the current module and add a link to the index
+constgtoc=gtocHTML.replace(
+`class="nav-${id}"`,`class="nav-${id} active"`
+).replace('</ul>',`
+ <li>
+ <a href="index.html">Index</a>
+ </li>
+ </ul>
+ `);
+
+return`
+ <li class="picker-header">
+ <a href="#">
+ <span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
+ Index
+ </a>
+
+ <div class="picker">${gtoc}</div>
+ </li>
+ `;
+}
+
+functiontocPicker(id,content){
+if(id==='index'){
+return'';
+}
+
+return`
+ <li class="picker-header">
+ <a href="#">
+ <span class="collapsed-arrow">&#x25ba;</span><span class="expanded-arrow">&#x25bc;</span>
+ Table of contents
+ </a>
+
+ <div class="picker">${content.tocPicker}</div>
+ </li>
+ `;
+}