Add browsable versions extension for scaladoc

Author: BarkingBad

scaladoc-js/src/Globals.scala

@@ -7,11 +7,12 @@ import scala.scalajs.js.annotation.JSGlobalScope
 @JSGlobalScope
 object Globals extends js.Object {
   val pathToRoot: String = js.native
+  val versionsDictionaryUrl: String = js.native
 }
 
 object StringUtils {
   def createCamelCaseTokens(s: String): List[String] =
     if s.isEmpty then List.empty
     else if s.tail.indexWhere(_.isUpper) == -1 then List(s)
     else List(s.take(s.tail.indexWhere(_.isUpper) + 1)) ++ createCamelCaseTokens(s.drop(s.tail.indexWhere(_.isUpper) + 1))
-}
+}

scaladoc-js/src/Main.scala

@@ -3,4 +3,5 @@ package dotty.tools.scaladoc
 object Main extends App {
   Searchbar()
   SocialLinks()
+  DropdownHandler()
 }

scaladoc-js/src/versions-dropdown/DropdownHandler.scala

@@ -0,0 +1,86 @@
+package dotty.tools.scaladoc
+
+import scala.concurrent.ExecutionContext.Implicits.global
+import scala.concurrent.Future
+import scala.util.{Success,Failure}
+
+import org.scalajs.dom._
+import org.scalajs.dom.ext._
+import scala.scalajs.js.annotation.JSExportTopLevel
+import org.scalajs.dom.ext.Ajax
+import scala.scalajs.js
+import scala.scalajs.js.JSON
+
+trait Versions extends js.Object:
+  def versions: js.Dictionary[String]
+
+class DropdownHandler:
+
+  val KEY = "versions-json"
+  val UNDEFINED_VERSIONS = "undefined_versions"
+
+  private def addVersionsList(json: String) =
+    val ver = JSON.parse(json).asInstanceOf[Versions]
+    val ddc = document.getElementById("dropdown-content")
+    for (k, v) <- ver.versions do
+      var child = document.createElement("a").asInstanceOf[html.Anchor]
+      child.href = v
+      child.text = k
+      ddc.appendChild(child)
+
+  private def disableButton() =
+    val btn = document.getElementById("dropdown-button").asInstanceOf[html.Button]
+    btn.disabled = true
+    btn.classList.remove("dropdownbtnactive")
+
+  private def getURLContent(url: String): Future[String] = Ajax.get(url).map(_.responseText)
+
+  window.localStorage.getItem(KEY) match
+    case null => // If no key, returns null
+      Globals.versionsDictionaryUrl match
+        case null => // global property not defined
+          // do nothing
+        case url: String =>
+          getURLContent(url).onComplete {
+            case Success(json: String) =>
+              window.localStorage.setItem(KEY, json)
+              addVersionsList(json)
+            case Failure(_) =>
+              window.localStorage.setItem(KEY, UNDEFINED_VERSIONS)
+              disableButton()
+          }
+    case value => value match
+      case UNDEFINED_VERSIONS =>
+        disableButton()
+      case json =>
+        addVersionsList(json)
+
+
+  document.onclick = (e: Event) => {
+    if e.target.asInstanceOf[html.Element].id != "dropdown-button" then
+      document.getElementById("dropdown-content").classList.remove("show")
+  }
+
+  document.getElementById("version").asInstanceOf[html.Span].onclick = (e: Event) => {
+    e.stopPropagation
+  }
+
+
+@JSExportTopLevel("dropdownHandler")
+def dropdownHandler() =
+  if document.getElementById("dropdown-content").getElementsByTagName("a").size > 0 then
+    document.getElementById("dropdown-content").classList.toggle("show")
+
+@JSExportTopLevel("filterFunction")
+def filterFunction() =
+  val input = document.getElementById("dropdown-input").asInstanceOf[html.Input]
+  val filter = input.value.toUpperCase
+  val div = document.getElementById("dropdown-content")
+  val a = div.getElementsByTagName("a")
+  for i <- 0 until a.length do
+    val txtValue = a(i).innerText
+    val disp = if txtValue.toUpperCase.indexOf(filter) > -1 then
+      ""
+    else
+      "none"
+    a(i).asInstanceOf[html.Anchor].style.display = disp

scaladoc/resources/dotty_res/styles/scalastyle.css

@@ -784,3 +784,63 @@ footer .socials {
 footer {
   background-color: white;
 }
+
+/* The container <div> - needed to position the dropdown content */
+.versions-dropdown {
+  position: relative;
+  display: inline-block;
+}
+
+ /* Dropdown Button */
+.dropdownbtn {
+  background-color: var(--leftbar-bg);
+  color: white;
+  padding: 4px 12px;
+  border: none;
+}
+
+/* Dropdown button on hover & focus */
+.dropdownbtnactive:hover, .dropdownbtnactive:focus {
+  background-color: var(--leftbar-hover-bg);
+  cursor: pointer;
+}
+
+/* The search field */
+#dropdown-input {
+  box-sizing: border-box;
+  background-image: url('searchicon.png');
+  background-position: 14px 12px;
+  background-repeat: no-repeat;
+  font-size: 16px;
+  padding: 14px 20px 12px 45px;
+  border: none;
+  border-bottom: 1px solid #ddd;
+}
+
+/* The search field when it gets focus/clicked on */
+#dropdown-input:focus {outline: 3px solid #ddd;}
+
+
+/* Dropdown Content (Hidden by Default) */
+.dropdown-content {
+  display: none;
+  position: absolute;
+  background-color: #f6f6f6;
+  min-width: 230px;
+  border: 1px solid #ddd;
+  z-index: 1;
+}
+
+/* Links inside the dropdown */
+.dropdown-content a {
+  color: black;
+  padding: 12px 16px;
+  text-decoration: none;
+  display: block;
+}
+
+/* Change color of dropdown links on hover */
+.dropdown-content a:hover {background-color: #f1f1f1}
+
+/* Show the dropdown menu (use JS to add this class to the .dropdown-content container when the user clicks on the dropdown button) */
+.show {display:block;}

scaladoc/src/dotty/tools/scaladoc/Scaladoc.scala

@@ -49,6 +49,7 @@ object Scaladoc:
     includePrivateAPI: Boolean = false,
     docCanonicalBaseUrl: String = "",
     documentSyntheticTypes: Boolean = false,
+    versionsDictionaryUrl: Option[String] = None
   )
 
   def run(args: Array[String], rootContext: CompilerContext): Reporter =
@@ -189,7 +190,8 @@ object Scaladoc:
         groups.get,
         visibilityPrivate.get,
         docCanonicalBaseUrl.get,
-        YdocumentSyntheticTypes.get
+        YdocumentSyntheticTypes.get,
+        versionsDictionaryUrl.nonDefault
       )
       (Some(docArgs), newContext)
     }

scaladoc/src/dotty/tools/scaladoc/ScaladocSettings.scala

@@ -92,5 +92,12 @@ class ScaladocSettings extends SettingGroup with AllScalaSettings:
     "./docs"
   )
 
+  val versionsDictionaryUrl: Setting[String] = StringSetting(
+    "-versions-dictionary-url",
+    "versions dictionary url",
+    "A URL pointing to json with dictionary version -> documentation location. Useful for libraries that maintain different releases docs",
+    ""
+  )
+
   val YdocumentSyntheticTypes: Setting[Boolean] =
     BooleanSetting("-Ydocument-synthetic-types", "Documents intrinsic types e. g. Any, Nothing. Setting is useful only for stdlib", false)

scaladoc/src/dotty/tools/scaladoc/renderers/HtmlRenderer.scala

@@ -141,7 +141,10 @@ class HtmlRenderer(rootPackage: Member, val members: Map[DRI, Member])(using ctx
         href := resolveLink(page.link.dri, "favicon.ico")
       ),
       linkResources(page.link.dri, resources).toList,
-      script(raw(s"""var pathToRoot = "${pathToRoot(page.link.dri)}";"""))
+      script(raw(s"""var pathToRoot = "${pathToRoot(page.link.dri)}";""")),
+      ctx.args.versionsDictionaryUrl match
+        case Some(url) => script(raw(s"""var versionsDictionaryUrl = "$url";"""))
+        case None => ""
     )
 
   private def buildNavigation(pageLink: Link): AppliedTag =
@@ -220,8 +223,13 @@ class HtmlRenderer(rootPackage: Member, val members: Map[DRI, Member])(using ctx
           span(
             div(cls:="projectName")(args.name)
           ),
-          span(
-            args.projectVersion.map(v => div(cls:="projectVersion")(v)).toList
+          span(id := "version")(
+            div(cls := "versions-dropdown")(
+              div(onclick := "dropdownHandler()", id := "dropdown-button", cls := "dropdownbtn dropdownbtnactive")(args.projectVersion.map(v => div(cls:="projectVersion")(v)).toList),
+              div(id := "dropdown-content", cls := "dropdown-content")(
+                input(`type` := "text", placeholder := "Search...", id := "dropdown-input", onkeyup := "filterFunction()"),
+              ),
+            )
           ),
           div(cls := "socials")(
             socialLinks()

scaladoc/src/dotty/tools/scaladoc/util/html.scala

@@ -99,6 +99,7 @@ object HTML:
   val value = Attr("value")
   val onclick=Attr("onclick")
   val titleAttr =Attr("title")
+  val onkeyup = Attr("onkeyup")
 
   def raw(content: String): AppliedTag = new AppliedTag(content)
   def raw(content: StringBuilder): AppliedTag = content