Change sidebar hiding strategy to avoid flickering on mobile devices

st0012 · st0012 · commit 83c8d7a890ab · 2025-12-21T18:56:28.000Z
Previously, the sidebar was hidden with JavaScript on small viewports.
This approach caused flickering when the page was loaded, especially on mobile devices.

Now, the sidebar is hidden by default with the `hidden` attribute.
On large viewports, we display the sidebar with JavaScript.
This approach avoids flickering when the page is loaded, especially on mobile devices.
diff --git a/lib/rdoc/generator/template/aliki/class.rhtml b/lib/rdoc/generator/template/aliki/class.rhtml
@@ -3,7 +3,7 @@
 <%= render '_header.rhtml' %>
 <%= render '_sidebar_toggle.rhtml' %>
 
-<nav id="navigation" role="navigation">
+<nav id="navigation" role="navigation" hidden>
   <%= render '_sidebar_pages.rhtml' %>
   <%= render '_sidebar_sections.rhtml' %>
   <%= render '_sidebar_ancestors.rhtml' %>
diff --git a/lib/rdoc/generator/template/aliki/index.rhtml b/lib/rdoc/generator/template/aliki/index.rhtml
@@ -3,7 +3,7 @@
 <%= render '_header.rhtml' %>
 <%= render '_sidebar_toggle.rhtml' %>
 
-<nav id="navigation" role="navigation">
+<nav id="navigation" role="navigation" hidden>
   <%= render '_sidebar_pages.rhtml' %>
   <%= render '_sidebar_classes.rhtml' %>
 </nav>
diff --git a/lib/rdoc/generator/template/aliki/js/aliki.js b/lib/rdoc/generator/template/aliki/js/aliki.js
@@ -158,9 +158,12 @@ function hookSidebar() {
   });
 
   const isSmallViewport = window.matchMedia("(max-width: 1023px)").matches;
-  if (isSmallViewport) {
-    closeNav();
 
+  // The sidebar is hidden by default with the `hidden` attribute
+  // On large viewports, we display the sidebar with JavaScript
+  // This is better than the opposite approach of hiding it with JavaScript
+  // because it avoids flickering the sidebar when the page is loaded, especially on mobile devices
+  if (isSmallViewport) {
     // Close nav when clicking links inside it
     document.addEventListener('click', (e) => {
       if (e.target.closest('#navigation a')) {
@@ -176,6 +179,8 @@ function hookSidebar() {
         closeNav();
       }
     });
+  } else {
+    openNav();
   }
 }
 
diff --git a/lib/rdoc/generator/template/aliki/page.rhtml b/lib/rdoc/generator/template/aliki/page.rhtml
@@ -3,7 +3,7 @@
 <%= render '_header.rhtml' %>
 <%= render '_sidebar_toggle.rhtml' %>
 
-<nav id="navigation" role="navigation">
+<nav id="navigation" role="navigation" hidden>
   <%= render '_sidebar_pages.rhtml' %>
   <%= render '_sidebar_classes.rhtml' %>
 </nav>
diff --git a/lib/rdoc/generator/template/aliki/servlet_not_found.rhtml b/lib/rdoc/generator/template/aliki/servlet_not_found.rhtml
@@ -1,7 +1,7 @@
 <body role="document">
 <%= render '_sidebar_toggle.rhtml' %>
 
-<nav id="navigation" role="navigation">
+<nav id="navigation" role="navigation" hidden>
   <%= render '_sidebar_pages.rhtml' %>
   <%= render '_sidebar_classes.rhtml' %>
 </nav>
diff --git a/lib/rdoc/generator/template/aliki/servlet_root.rhtml b/lib/rdoc/generator/template/aliki/servlet_root.rhtml
@@ -1,7 +1,7 @@
 <body role="document">
 <%= render '_sidebar_toggle.rhtml' %>
 
-<nav id="navigation" role="navigation">
+<nav id="navigation" role="navigation" hidden>
   <div id="project-navigation">
     <div id="home-section" class="nav-section">
       <h2>
diff --git a/test/rdoc/generator/aliki_test.rb b/test/rdoc/generator/aliki_test.rb
@@ -228,7 +228,7 @@ def test_generate
     index = File.binread('index.html')
     assert_match %r{<html lang="en">}, index
     assert_match %r{<body role="document"}, index
-    assert_match %r{<nav id="navigation" role="navigation">}, index
+    assert_match %r{<nav id="navigation" role="navigation" hidden>}, index
     assert_match %r{<main role="main">}, index
   end
 
