From 8e6dfc2e3d8a011f6928940e7c11db3f451c95bc Mon Sep 17 00:00:00 2001
From: Leo Kettmeir <crowlkats@toaxl.com>
Date: Fri, 12 Jul 2024 23:51:13 +0200
Subject: [PATCH] fix(html): correctly handle examples in document navigation
 (#612)

---
 src/html/comrak_adapters.rs                   |   2 +-
 src/html/jsdoc.rs                             |  51 ++++-
 src/html/symbols/mod.rs                       |  10 +-
 src/html/util.rs                              |  15 +-
 .../html_test__html_doc_files_rewrite-21.snap |   2 +-
 tests/snapshots/html_test__symbol_group.snap  | 197 +++++++++---------
 6 files changed, 166 insertions(+), 111 deletions(-)

diff --git a/src/html/comrak_adapters.rs b/src/html/comrak_adapters.rs
index d4586f77..5a46d37b 100644
--- a/src/html/comrak_adapters.rs
+++ b/src/html/comrak_adapters.rs
@@ -285,7 +285,7 @@ impl HeadingToCAdapter {
     }
 
     let mut toc_content = vec!["<ul>".to_string()];
-    let mut current_level = toc.first().unwrap().level;
+    let mut current_level = toc.iter().map(|entry| entry.level).min().unwrap();
 
     for entry in toc {
       match current_level.cmp(&entry.level) {
diff --git a/src/html/jsdoc.rs b/src/html/jsdoc.rs
index a0d44f7d..ca753d23 100644
--- a/src/html/jsdoc.rs
+++ b/src/html/jsdoc.rs
@@ -1,5 +1,7 @@
 use super::render_context::RenderContext;
 use super::util::*;
+#[cfg(feature = "ammonia")]
+use crate::html::comrak_adapters::URLRewriter;
 use crate::html::ShortPath;
 use crate::js_doc::JsDoc;
 use crate::js_doc::JsDocTag;
@@ -12,9 +14,8 @@ use comrak::Arena;
 use serde::Serialize;
 use std::borrow::Cow;
 use std::cell::RefCell;
-
-#[cfg(feature = "ammonia")]
-use crate::html::comrak_adapters::URLRewriter;
+use std::io::BufWriter;
+use std::io::Write;
 
 lazy_static! {
   static ref JSDOC_LINK_RE: regex::Regex = regex::Regex::new(
@@ -298,7 +299,7 @@ fn render_node<'a>(
   options: &comrak::Options,
   plugins: &comrak::Plugins,
 ) -> String {
-  let mut bw = std::io::BufWriter::new(Vec::new());
+  let mut bw = BufWriter::new(Vec::new());
   comrak::format_html_with_plugins(node, options, &mut bw, plugins).unwrap();
   String::from_utf8(bw.into_inner().unwrap()).unwrap()
 }
@@ -309,6 +310,46 @@ pub struct MarkdownToHTMLOptions {
   pub no_toc: bool,
 }
 
+pub fn strip(render_ctx: &RenderContext, md: &str) -> String {
+  let mut options = comrak::Options::default();
+  options.extension.autolink = true;
+  options.extension.description_lists = true;
+  options.extension.strikethrough = true;
+  options.extension.superscript = true;
+  options.extension.table = true;
+  options.extension.tagfilter = true;
+  options.extension.tasklist = true;
+  options.render.escape = true;
+
+  let md = parse_links(md, render_ctx);
+
+  let arena = Arena::new();
+  let root = comrak::parse_document(&arena, &md, &options);
+
+  walk_node(&arena, root, &options, &Default::default());
+
+  fn collect_text<'a>(node: &'a AstNode<'a>, output: &mut BufWriter<Vec<u8>>) {
+    match node.data.borrow().value {
+      NodeValue::Text(ref literal)
+      | NodeValue::Code(comrak::nodes::NodeCode { ref literal, .. }) => {
+        output.write_all(literal.as_bytes()).unwrap();
+      }
+      NodeValue::LineBreak | NodeValue::SoftBreak => {
+        output.write_all(&[b' ']).unwrap()
+      }
+      _ => {
+        for n in node.children() {
+          collect_text(n, output);
+        }
+      }
+    }
+  }
+
+  let mut bw = BufWriter::new(Vec::new());
+  collect_text(root, &mut bw);
+  String::from_utf8(bw.into_inner().unwrap()).unwrap()
+}
+
 pub fn markdown_to_html(
   render_ctx: &RenderContext,
   md: &str,
@@ -529,6 +570,7 @@ pub(crate) fn jsdoc_examples(
 pub struct ExampleCtx {
   pub anchor: AnchorCtx,
   pub id: String,
+  pub title: String,
   pub markdown_title: String,
   markdown_body: String,
 }
@@ -553,6 +595,7 @@ impl ExampleCtx {
     ExampleCtx {
       anchor: AnchorCtx { id: id.to_string() },
       id: id.to_string(),
+      title,
       markdown_title,
       markdown_body,
     }
diff --git a/src/html/symbols/mod.rs b/src/html/symbols/mod.rs
index f832f97c..74539d37 100644
--- a/src/html/symbols/mod.rs
+++ b/src/html/symbols/mod.rs
@@ -287,10 +287,12 @@ impl SymbolInnerCtx {
       let docs =
         crate::html::jsdoc::jsdoc_body_to_html(ctx, &doc_node.js_doc, false);
 
-      if let Some(examples) =
-        crate::html::jsdoc::jsdoc_examples(ctx, &doc_node.js_doc)
-      {
-        sections.push(examples);
+      if doc_node.kind != DocNodeKind::Function {
+        if let Some(examples) =
+          crate::html::jsdoc::jsdoc_examples(ctx, &doc_node.js_doc)
+        {
+          sections.push(examples);
+        }
       }
 
       sections.extend(match doc_node.kind {
diff --git a/src/html/util.rs b/src/html/util.rs
index 51975898..4ddf432c 100644
--- a/src/html/util.rs
+++ b/src/html/util.rs
@@ -488,7 +488,20 @@ impl SectionCtx {
           render_context.toc.add_entry(2, name.clone(), anchor);
         }
       }
-      SectionContentCtx::Example(_) => {}
+      SectionContentCtx::Example(examples) => {
+        for example in examples {
+          let anchor = render_context.toc.anchorize(example.id.to_owned());
+
+          example.id = anchor.clone();
+          example.anchor.id = anchor.clone();
+
+          render_context.toc.add_entry(
+            2,
+            super::jsdoc::strip(render_context, &example.title),
+            anchor,
+          );
+        }
+      }
       SectionContentCtx::IndexSignature(_) => {}
       SectionContentCtx::NamespaceSection(nodes) => {
         for node in nodes {
diff --git a/tests/snapshots/html_test__html_doc_files_rewrite-21.snap b/tests/snapshots/html_test__html_doc_files_rewrite-21.snap
index 94375f24..6e74eec6 100644
--- a/tests/snapshots/html_test__html_doc_files_rewrite-21.snap
+++ b/tests/snapshots/html_test__html_doc_files_rewrite-21.snap
@@ -3,5 +3,5 @@ source: tests/html_test.rs
 expression: "files.get(\"search_index.js\").unwrap()"
 ---
 (function () {
-  window.DENO_DOC_SEARCH_INDEX = {"nodes":[{"kind":["class"],"name":"A","file":".","doc":"","location":{"filename":".","line":45,"col":0,"byteIndex":741},"url":"././~/A.html","category":"","declarationKind":"private","deprecated":false},{"kind":["class"],"name":"B","file":".","doc":"","location":{"filename":".","line":48,"col":0,"byteIndex":770},"url":"././~/B.html","category":"","declarationKind":"export","deprecated":false},{"kind":["class"],"name":"Bar","file":".","doc":"","location":{"filename":".","line":31,"col":0,"byteIndex":588},"url":"././~/Bar.html","category":"","declarationKind":"export","deprecated":false},{"kind":["typeAlias"],"name":"Baz","file":".","doc":"","location":{"filename":".","line":41,"col":0,"byteIndex":702},"url":"././~/Baz.html","category":"","declarationKind":"export","deprecated":false},{"kind":["class"],"name":"Foo","file":".","doc":"some Foo docs","location":{"filename":".","line":25,"col":0,"byteIndex":488},"url":"././~/Foo.html","category":"","declarationKind":"export","deprecated":false},{"kind":["class"],"name":"Foobar","file":".","doc":"","location":{"filename":".","line":34,"col":0,"byteIndex":622},"url":"././~/Foobar.html","category":"","declarationKind":"export","deprecated":false},{"kind":["interface"],"name":"Hello","file":".","doc":"","location":{"filename":".","line":37,"col":0,"byteIndex":655},"url":"././~/Hello.html","category":"","declarationKind":"export","deprecated":false},{"kind":["function"],"name":"c","file":".","doc":"","location":{"filename":".","line":57,"col":13,"byteIndex":933},"url":"././~/c.html","category":"","declarationKind":"export","deprecated":false},{"kind":["function","function","function"],"name":"qaz","file":".","doc":"","location":{"filename":".","line":53,"col":0,"byteIndex":812},"url":"././~/qaz.html","category":"","declarationKind":"export","deprecated":false},{"kind":["variable"],"name":"default","file":"foo","doc":"The default export item.\n\nThis item reproduces the issue reported in {@link https://github.com/jsr-io/jsr/issues/459}","location":{"filename":"foo","line":7,"col":6,"byteIndex":167},"url":"./foo/~/default.html","category":"","declarationKind":"export","deprecated":false},{"kind":["function"],"name":"x","file":"foo","doc":"","location":{"filename":"foo","line":1,"col":0,"byteIndex":0},"url":"./foo/~/x.html","category":"","declarationKind":"export","deprecated":false}]};
+  window.DENO_DOC_SEARCH_INDEX = {"nodes":[{"kind":["class"],"name":"A","file":".","doc":"","location":{"filename":".","line":45,"col":0,"byteIndex":741},"url":"././~/A.html","category":"","declarationKind":"private","deprecated":false},{"kind":["class"],"name":"B","file":".","doc":"","location":{"filename":".","line":48,"col":0,"byteIndex":770},"url":"././~/B.html","category":"","declarationKind":"export","deprecated":false},{"kind":["class"],"name":"Bar","file":".","doc":"","location":{"filename":".","line":31,"col":0,"byteIndex":588},"url":"././~/Bar.html","category":"","declarationKind":"export","deprecated":false},{"kind":["typeAlias"],"name":"Baz","file":".","doc":"","location":{"filename":".","line":41,"col":0,"byteIndex":702},"url":"././~/Baz.html","category":"","declarationKind":"export","deprecated":false},{"kind":["class"],"name":"Foo","file":".","doc":"some Foo docs","location":{"filename":".","line":25,"col":0,"byteIndex":488},"url":"././~/Foo.html","category":"","declarationKind":"export","deprecated":false},{"kind":["class"],"name":"Foobar","file":".","doc":"","location":{"filename":".","line":34,"col":0,"byteIndex":622},"url":"././~/Foobar.html","category":"","declarationKind":"export","deprecated":false},{"kind":["interface"],"name":"Hello","file":".","doc":"","location":{"filename":".","line":37,"col":0,"byteIndex":655},"url":"././~/Hello.html","category":"","declarationKind":"export","deprecated":false},{"kind":["function"],"name":"c","file":".","doc":"","location":{"filename":".","line":57,"col":13,"byteIndex":933},"url":"././~/c.html","category":"","declarationKind":"export","deprecated":false},{"kind":["function"],"name":"d","file":".","doc":"","location":{"filename":".","line":59,"col":0,"byteIndex":961},"url":"././~/d.html","category":"","declarationKind":"export","deprecated":false},{"kind":["function","function","function"],"name":"qaz","file":".","doc":"","location":{"filename":".","line":53,"col":0,"byteIndex":812},"url":"././~/qaz.html","category":"","declarationKind":"export","deprecated":false},{"kind":["variable"],"name":"default","file":"foo","doc":"The default export item.\n\nThis item reproduces the issue reported in {@link https://github.com/jsr-io/jsr/issues/459}","location":{"filename":"foo","line":7,"col":6,"byteIndex":167},"url":"./foo/~/default.html","category":"","declarationKind":"export","deprecated":false},{"kind":["function"],"name":"x","file":"foo","doc":"","location":{"filename":"foo","line":1,"col":0,"byteIndex":0},"url":"./foo/~/x.html","category":"","declarationKind":"export","deprecated":false}]};
 })()
diff --git a/tests/snapshots/html_test__symbol_group.snap b/tests/snapshots/html_test__symbol_group.snap
index ea29b754..b3595666 100644
--- a/tests/snapshots/html_test__symbol_group.snap
+++ b/tests/snapshots/html_test__symbol_group.snap
@@ -853,114 +853,111 @@ expression: files
             {
               "kind": "function",
               "value": {
-                "overloads_ctx": [
+                "functions": [
                   {
-                    "function_id": "function_d",
-                    "overload_id": "function_d_0",
-                    "additional_css": "\n#function_d_0 {\n  display: none;\n}\n#function_d_0:checked ~ *:last-child > :not(#function_d_0_div) {\n  display: none;\n}\n#function_d_0:checked ~ div:first-of-type > label[for='function_d_0'] {\n  background-color: var(--ddoc-selection-selected-bg);\n  border: solid var(--ddoc-selection-border-width) var(--ddoc-selection-selected-border-color);\n  cursor: unset;\n  padding: var(--ddoc-selection-padding); /* 1px less to counter the increased border */\n}\n\n.ddoc:has(#function_d_0:not(:checked)) #function_d_0_toc {\n  display: none;\n}\n",
-                    "html_attrs": "checked",
+                    "id": "function_d_0",
+                    "anchor": {
+                      "id": "function_d_0"
+                    },
                     "name": "d",
+                    "summary": "(<div class=\"ml-4\"><div><span>foo?<span>: <span>number</span></span></span>,</div><div><span>bar?<span>: <span>string</span></span></span>,</div><div><span>baz?<span>: { hello?<span>: <span>string</span></span>;  }</span></span>,</div></div>)<span>: <span>string</span></span>",
                     "deprecated": null,
-                    "summary": "(<span><span>foo?<span>: <span>number</span></span></span><span>, </span><span>bar?<span>: <span>string</span></span></span><span>, </span><span>baz?<span>: { hello?<span>: <span>string</span></span>;  }</span></span></span>)<span>: <span>string</span></span>",
-                    "summary_doc": null
-                  }
-                ],
-                "functions": [
-                  {
-                    "id": "function_d_0_div",
-                    "docs": null,
-                    "sections": [
-                      {
-                        "header": {
-                          "title": "Parameters",
-                          "anchor": {
-                            "id": "parameters"
+                    "content": {
+                      "id": "",
+                      "docs": null,
+                      "sections": [
+                        {
+                          "header": {
+                            "title": "Parameters",
+                            "anchor": {
+                              "id": "parameters"
+                            },
+                            "href": null,
+                            "doc": null
                           },
-                          "href": null,
-                          "doc": null
-                        },
-                        "content": {
-                          "kind": "doc_entry",
-                          "content": [
-                            {
-                              "id": "function_d_0_parameters_foo",
-                              "name": "foo",
-                              "name_href": null,
-                              "content": "<span>: <span>number</span></span><span><span class=\"font-normal\"> = </span>1</span>",
-                              "anchor": {
-                                "id": "function_d_0_parameters_foo"
+                          "content": {
+                            "kind": "doc_entry",
+                            "content": [
+                              {
+                                "id": "function_d_0_parameters_foo",
+                                "name": "foo",
+                                "name_href": null,
+                                "content": "<span>: <span>number</span></span><span><span class=\"font-normal\"> = </span>1</span>",
+                                "anchor": {
+                                  "id": "function_d_0_parameters_foo"
+                                },
+                                "tags": [
+                                  {
+                                    "kind": "optional"
+                                  }
+                                ],
+                                "js_doc": null,
+                                "source_href": null
                               },
-                              "tags": [
-                                {
-                                  "kind": "optional"
-                                }
-                              ],
-                              "js_doc": null,
-                              "source_href": null
-                            },
-                            {
-                              "id": "function_d_0_parameters_bar",
-                              "name": "bar",
-                              "name_href": null,
-                              "content": "<span>: <span>string</span></span><span><span class=\"font-normal\"> = </span>bar</span>",
-                              "anchor": {
-                                "id": "function_d_0_parameters_bar"
+                              {
+                                "id": "function_d_0_parameters_bar",
+                                "name": "bar",
+                                "name_href": null,
+                                "content": "<span>: <span>string</span></span><span><span class=\"font-normal\"> = </span>bar</span>",
+                                "anchor": {
+                                  "id": "function_d_0_parameters_bar"
+                                },
+                                "tags": [
+                                  {
+                                    "kind": "optional"
+                                  }
+                                ],
+                                "js_doc": null,
+                                "source_href": null
                               },
-                              "tags": [
-                                {
-                                  "kind": "optional"
-                                }
-                              ],
-                              "js_doc": null,
-                              "source_href": null
+                              {
+                                "id": "function_d_0_parameters_baz",
+                                "name": "baz",
+                                "name_href": null,
+                                "content": "<span>: { hello?<span>: <span>string</span></span>;  }</span>",
+                                "anchor": {
+                                  "id": "function_d_0_parameters_baz"
+                                },
+                                "tags": [
+                                  {
+                                    "kind": "optional"
+                                  }
+                                ],
+                                "js_doc": null,
+                                "source_href": null
+                              }
+                            ]
+                          }
+                        },
+                        {
+                          "header": {
+                            "title": "Return Type",
+                            "anchor": {
+                              "id": "return-type"
                             },
-                            {
-                              "id": "function_d_0_parameters_baz",
-                              "name": "baz",
-                              "name_href": null,
-                              "content": "<span>: { hello?<span>: <span>string</span></span>;  }</span>",
-                              "anchor": {
-                                "id": "function_d_0_parameters_baz"
-                              },
-                              "tags": [
-                                {
-                                  "kind": "optional"
-                                }
-                              ],
-                              "js_doc": null,
-                              "source_href": null
-                            }
-                          ]
-                        }
-                      },
-                      {
-                        "header": {
-                          "title": "Return Type",
-                          "anchor": {
-                            "id": "return-type"
+                            "href": null,
+                            "doc": null
                           },
-                          "href": null,
-                          "doc": null
-                        },
-                        "content": {
-                          "kind": "doc_entry",
-                          "content": [
-                            {
-                              "id": "function_d_0_return",
-                              "name": "",
-                              "name_href": null,
-                              "content": "<span>string</span>",
-                              "anchor": {
-                                "id": "function_d_0_return"
-                              },
-                              "tags": [],
-                              "js_doc": null,
-                              "source_href": null
-                            }
-                          ]
+                          "content": {
+                            "kind": "doc_entry",
+                            "content": [
+                              {
+                                "id": "function_d_0_return",
+                                "name": null,
+                                "name_href": null,
+                                "content": "<span>string</span>",
+                                "anchor": {
+                                  "id": "function_d_0_return"
+                                },
+                                "tags": [],
+                                "js_doc": null,
+                                "source_href": null
+                              }
+                            ]
+                          }
                         }
-                      }
-                    ]
+                      ]
+                    }
                   }
                 ]
               }
@@ -1000,7 +997,7 @@ expression: files
         "composed": false
       },
       "top_symbols": null,
-      "document_navigation": "<ul id=\"function_d_0_toc\"><li><a href=\"#parameters\" title=\"Parameters\">Parameters</a></li><li><ul><li><a href=\"#function_d_0_parameters_foo\" title=\"foo\">foo</a></li><li><a href=\"#function_d_0_parameters_bar\" title=\"bar\">bar</a></li><li><a href=\"#function_d_0_parameters_baz\" title=\"baz\">baz</a></li></ul></li><li><a href=\"#return-type\" title=\"Return Type\">Return Type</a></li><li><ul><li><a href=\"#function_d_0_return\" title=\"\"></a></li></ul>"
+      "document_navigation": "<ul><li><a href=\"#parameters\" title=\"Parameters\">Parameters</a></li><li><ul><li><a href=\"#function_d_0_parameters_foo\" title=\"foo\">foo</a></li><li><a href=\"#function_d_0_parameters_bar\" title=\"bar\">bar</a></li><li><a href=\"#function_d_0_parameters_baz\" title=\"baz\">baz</a></li></ul></li><li><a href=\"#return-type\" title=\"Return Type\">Return Type</a></li></ul>"
     },
     "disable_search": false,
     "categories_panel": null