From 0d65597245de6bad92025fe8b913fa9ee486f66c Mon Sep 17 00:00:00 2001
From: Jonathan Hefner <jonathan@hefner.pro>
Date: Fri, 21 Jul 2023 15:07:46 -0500
Subject: [PATCH] Replace source code toggler JavaScript with <details>

This commit replaces the `javascript:toggleSource(...)` links used to
show and hide method source with an inherently toggleable `<details>`
element.  In addition to reducing JavaScript, this fixes a small
horizontal shift that occurred when changing "show" to "hide" (and vice
versa).

The `external-link.svg` file is from [Feather icons][feather] v4.29.0,
and is [licensed under the MIT license][license].

[feather]: https://feathericons.com/
[license]: https://github.com/feathericons/feather/blob/v4.29.0/LICENSE
---
 .../generator/template/rails/_context.rhtml   | 41 ++++++--------
 .../template/rails/resources/css/main.css     | 53 +++++++++++++++----
 .../rails/resources/i/external-link.svg       |  1 +
 .../template/rails/resources/js/main.js       |  6 ---
 lib/sdoc/helpers.rb                           |  8 +++
 spec/helpers_spec.rb                          | 22 ++++++++
 6 files changed, 90 insertions(+), 41 deletions(-)
 create mode 100644 lib/rdoc/generator/template/rails/resources/i/external-link.svg

diff --git a/lib/rdoc/generator/template/rails/_context.rhtml b/lib/rdoc/generator/template/rails/_context.rhtml
index 994de3ab..748ba2c5 100644
--- a/lib/rdoc/generator/template/rails/_context.rhtml
+++ b/lib/rdoc/generator/template/rails/_context.rhtml
@@ -159,32 +159,25 @@
           <% end %>
 
           <% source_code, source_url = method_source_code_and_url(method) %>
-          <% if source_code || source_url %>
-            <div class="sourcecode">
-              <p class="source-link">
-                Source:
-
-                <% if source_code %>
-                  <a href="javascript:toggleSource('<%= method.aref %>_source')" id="l_<%= method.aref %>_source">show</a>
-                <% end %>
-
-                <% if source_code && source_url %> | <% end %>
-
+          <% if source_code %>
+            <details class="sourcecode">
+              <summary>
+                <span class="label">Source code</span>
                 <% if source_url %>
-                  <a href="<%= source_url %>" target="_blank" class="github_url">on GitHub</a>
+                  <%= link_to_external "GitHub", source_url %>
                 <% end %>
-              </p>
-
-              <% if source_code %>
-                <div id="<%= method.aref %>_source" class="dyn-source">
-                  <pre><code class="ruby"><%= source_code %></code></pre>
-                </div>
-              <% end %>
-            </div>
-            <% end %>
-          </div>
-        <% end %><%# methods.each %>
-      <% end %><%# visibilities.each %>
+              </summary>
+
+              <div class="dyn-source">
+                <pre><code class="ruby"><%= source_code %></code></pre>
+              </div>
+            </details>
+          <% elsif source_url %>
+            <p><%= link_to_external "GitHub", source_url %></p>
+          <% end %>
+        </div>
+      <% end %><%# methods.each %>
+    <% end %><%# visibilities.each %>
     <% end %><%# context.methods_by_type %>
   <% end %><%# context.each_section %>
 
diff --git a/lib/rdoc/generator/template/rails/resources/css/main.css b/lib/rdoc/generator/template/rails/resources/css/main.css
index 6c609713..2b3bb1d1 100644
--- a/lib/rdoc/generator/template/rails/resources/css/main.css
+++ b/lib/rdoc/generator/template/rails/resources/css/main.css
@@ -12,6 +12,10 @@ body {
   display: grid;
   grid-template-rows: min-content min-content auto min-content;
   grid-template-columns: 300px auto;
+
+  --link-color: #CC0000;
+  --link-hover-color: #990000;
+  --icon-color: #777777;
 }
 
 body {
@@ -61,12 +65,12 @@ body {
 }
 
 a:link, a:active, a:visited, a:hover {
-  color: #CC0000;
+  color: var(--link-color);
   text-decoration: none;
 }
 
 a:hover {
-  color: #990000;
+  color: var(--link-hover-color);
   text-decoration: underline;
 }
 
@@ -78,6 +82,13 @@ h1 a, h2 a, .banner a {
   color: #fff;
 }
 
+.external-link {
+  padding-left: 1.3em;
+  background-image: url('../i/external-link.svg');
+  background-repeat: no-repeat;
+  background-size: 1.1em;
+}
+
 p {
   margin-bottom: 1em;
 }
@@ -290,7 +301,6 @@ tt {
 }
 
 .dyn-source {
-  display: none;
   background: #fffde8;
   color: #000;
   border: #ffe0bb dotted 1px;
@@ -343,19 +353,40 @@ tt {
   top: 0;
 }
 
-.method .sourcecode p.source-link {
-  text-indent: 0em;
-  margin-top: 0.5em;
-}
-
 .method .aka {
   margin-left: 1.2em;
   font-style: italic;
 }
 
-.method .source-link
-{
-    font-size: 0.85em;
+.sourcecode {
+  width: fit-content; /* Reduce clickable area when collapsed */
+}
+
+.sourcecode[open] {
+  width: auto;
+}
+
+.sourcecode summary {
+  cursor: pointer;
+}
+
+.sourcecode summary::marker {
+  font-size: 1.25em;
+  color: var(--icon-color);
+}
+
+.sourcecode summary .label {
+  margin-left: -0.4em;
+  font-weight: bold;
+  color: var(--link-color);
+}
+
+.sourcecode summary .label:hover {
+  color: var(--link-hover-color);
+}
+
+.sourcecode summary .external-link {
+  margin-left: 1em;
 }
 
 @keyframes spotlight {
diff --git a/lib/rdoc/generator/template/rails/resources/i/external-link.svg b/lib/rdoc/generator/template/rails/resources/i/external-link.svg
new file mode 100644
index 00000000..31c1df5b
--- /dev/null
+++ b/lib/rdoc/generator/template/rails/resources/i/external-link.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="#777777" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-external-link"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path><polyline points="15 3 21 3 21 9"></polyline><line x1="10" y1="14" x2="21" y2="3"></line></svg>
diff --git a/lib/rdoc/generator/template/rails/resources/js/main.js b/lib/rdoc/generator/template/rails/resources/js/main.js
index 70ebbc0b..6bf81bff 100644
--- a/lib/rdoc/generator/template/rails/resources/js/main.js
+++ b/lib/rdoc/generator/template/rails/resources/js/main.js
@@ -1,9 +1,3 @@
-function toggleSource(id) {
-  var src = $('#' + id).toggle();
-  var isVisible = src.is(':visible');
-  $('#l_' + id).html(isVisible ? 'hide' : 'show');
-}
-
 window.spotlight = function(url) {
   var hash = url.match(/#([^#]+)$/);
   if (hash) {
diff --git a/lib/sdoc/helpers.rb b/lib/sdoc/helpers.rb
index bf9934df..d47aab1a 100644
--- a/lib/sdoc/helpers.rb
+++ b/lib/sdoc/helpers.rb
@@ -33,6 +33,14 @@ def link_to(text, url, html_attributes = {})
     %(<a href="#{h url}"#{attribute_string}>#{h text}</a>)
   end
 
+  def link_to_external(text, url, html_attributes = {})
+    html_attributes = html_attributes.transform_keys(&:to_s)
+    html_attributes = { "target" => "_blank", "class" => nil }.merge(html_attributes)
+    html_attributes["class"] = [*html_attributes["class"], "external-link"].join(" ")
+
+    link_to(text, url, html_attributes)
+  end
+
   def base_tag_for_context(context)
     if context == :index
       %(<base href="./" data-current-path=".">)
diff --git a/spec/helpers_spec.rb b/spec/helpers_spec.rb
index bd6bc4cc..58abb4a4 100644
--- a/spec/helpers_spec.rb
+++ b/spec/helpers_spec.rb
@@ -135,6 +135,28 @@ module Foo; class Bar; def qux; end; end; end
     end
   end
 
+  describe "#link_to_external" do
+    it "sets class='external-link' and target='_blank' by default" do
+      _(@helpers.link_to_external("foo", "bar")).
+        must_equal %(<a href="bar" target="_blank" class="external-link">foo</a>)
+    end
+
+    it "supports additional classes" do
+      _(@helpers.link_to_external("foo", "bar", class: "qux")).
+        must_equal %(<a href="bar" target="_blank" class="qux external-link">foo</a>)
+    end
+
+    it "supports overriding target" do
+      _(@helpers.link_to_external("foo", "bar", target: "_self")).
+        must_equal %(<a href="bar" target="_self" class="external-link">foo</a>)
+    end
+
+    it "supports additional attributes" do
+      _(@helpers.link_to_external("foo", "bar", "data-hoge": "fuga")).
+        must_equal %(<a href="bar" target="_blank" class="external-link" data-hoge="fuga">foo</a>)
+    end
+  end
+
   describe "#base_tag_for_context" do
     it "returns an idempotent <base> tag for the :index context" do
       _(@helpers.base_tag_for_context(:index)).