From b222f02a5f86a23222450aa5a949e0d830797b56 Mon Sep 17 00:00:00 2001
From: Michael Howell <michael@notriddle.com>
Date: Thu, 8 Feb 2024 15:00:29 -0700
Subject: [PATCH] drustdoc: add three-column layout for large desktops

This commit adds a floating TOC box to the right,
leaving the sibling/module/crate navigation on the left.

This kicks in at a size a little below 1920x1080, where
desktops with very wide monitors are: it's also around
the point where the content area can be full width while
allowing two sidebars. It only kicks in if the browser
supports grid layouts, but that should be most of them,
and we can't get rid of the two-column layout anyway,
since it's the layout you get on something like a portrait iPad.

This design, where it can be used, is meant to clearly split up
the table of contents and the site navigation, so the right
side floating box has the same color as the page while the left
sidebar does not. It also pushes it down further, so that it's
not as high as the search bar, though that's a bit more
subtle than the color.
---
 src/librustdoc/html/static/css/rustdoc.css | 130 +++++++++++++++++++--
 src/librustdoc/html/static/js/main.js      |  24 +++-
 src/librustdoc/html/templates/page.html    |  32 ++---
 src/librustdoc/html/templates/sidebar.html |  21 ++--
 tests/rustdoc-gui/sidebar.goml             |  24 ++--
 tests/rustdoc/sidebar/top-toc-html.rs      |   6 +-
 tests/rustdoc/sidebar/top-toc-idmap.rs     |  10 +-
 7 files changed, 190 insertions(+), 57 deletions(-)

diff --git a/src/librustdoc/html/static/css/rustdoc.css b/src/librustdoc/html/static/css/rustdoc.css
index 2a129f86dc518..80d2e3a065bd1 100644
--- a/src/librustdoc/html/static/css/rustdoc.css
+++ b/src/librustdoc/html/static/css/rustdoc.css
@@ -15,6 +15,8 @@
 	--desktop-sidebar-width: 200px;
 	--src-sidebar-width: 300px;
 	--desktop-sidebar-z-index: 100;
+	--width-limiter-width: 960px;
+	--desktop-grid-column-gap: 45px;
 }
 
 /* See FiraSans-LICENSE.txt for the Fira Sans license. */
@@ -317,7 +319,7 @@ button#toggle-all-docs {
 main {
 	position: relative;
 	flex-grow: 1;
-	padding: 10px 15px 40px 45px;
+	padding: 10px 15px 40px var(--desktop-grid-column-gap);
 	min-width: 0; /* avoid growing beyond the size limit */
 }
 
@@ -326,7 +328,7 @@ main {
 }
 
 .width-limiter {
-	max-width: 960px;
+	max-width: var(--width-limiter-width);
 	margin-right: auto;
 }
 
@@ -441,7 +443,7 @@ img {
 .sidebar-resizing .sidebar {
 	position: fixed;
 }
-.sidebar-resizing > body {
+.sidebar-resizing .rustdoc {
 	padding-left: var(--resizing-sidebar-width);
 }
 
@@ -515,7 +517,7 @@ img {
 	scrollbar-width: initial;
 	scrollbar-color: var(--scrollbar-color);
 }
-.sidebar {
+.sidebar, #TOC section, #ModNav section {
 	scrollbar-width: thin;
 	scrollbar-color: var(--scrollbar-color);
 }
@@ -524,17 +526,24 @@ img {
 ::-webkit-scrollbar {
 	width: 12px;
 }
-.sidebar::-webkit-scrollbar {
+.sidebar::-webkit-scrollbar,
+#TOC section::-webkit-scrollbar,
+#ModNav section::-webkit-scrollbar {
 	width: 8px;
 }
 ::-webkit-scrollbar-track {
 	-webkit-box-shadow: inset 0;
 	background-color: var(--scrollbar-track-background-color);
 }
-.sidebar::-webkit-scrollbar-track {
+.sidebar::-webkit-scrollbar-track,
+#TOC section::-webkit-scrollbar-track,
+#ModNav section::-webkit-scrollbar-track {
 	background-color: var(--scrollbar-track-background-color);
 }
-::-webkit-scrollbar-thumb, .sidebar::-webkit-scrollbar-thumb {
+::-webkit-scrollbar-thumb,
+.sidebar::-webkit-scrollbar-thumb,
+#TOC section::-webkit-scrollbar-thumb,
+#ModNav section::-webkit-scrollbar-thumb {
 	background-color: var(--scrollbar-thumb-background-color);
 }
 
@@ -675,7 +684,7 @@ ul.block, .block li, .block ul {
 	overflow-wrap: break-word;
 }
 
-.sidebar-crate + .version {
+.sidebar > .version {
 	margin-top: -1rem;
 	margin-bottom: 1rem;
 }
@@ -1853,6 +1862,111 @@ However, it's not needed with smaller screen width because the doc/code block is
 
 /* Media Queries */
 
+/* Very-large-screen mode. */
+@supports (display: grid) and (display: contents) {
+	@media (min-width: 1600px) and (min-height: 800px) {
+		.rustdoc:not(.src) {
+			display: grid;
+			grid-template-columns:
+				var(--desktop-sidebar-width)
+				var(--width-limiter-width)
+				minmax(0, 1fr);
+			grid-template-rows: min-content 1fr;
+			grid-template-areas:
+				"sidebar-title main sidebar-cratenav"
+				"sidebar-modnav main sidebar-toc";
+			grid-column-gap: var(--desktop-grid-column-gap);
+		}
+		.sidebar-resizing .rustdoc:not(.src) {
+			padding-left: 0;
+		}
+		.hide-sidebar .rustdoc:not(.src) {
+			grid-template-columns:
+				var(--width-limiter-width)
+				minmax(0, 1fr);
+			grid-template-rows: minmax(min-content, calc(64px + 0.75rem)) 1fr;
+			grid-template-areas:
+				"main sidebar-cratenav"
+				"main sidebar-toc";
+			padding-left: var(--desktop-grid-column-gap);
+		}
+		.rustdoc:not(.src) .sidebar,
+		.rustdoc:not(.src) main {
+			display: contents;
+		}
+		.width-limiter {
+			grid-area: main;
+			width: var(--width-limiter-width);
+			--desktop-sidebar-width: 0;
+		}
+		.rustdoc:not(.src) nav.sub {
+			padding-top: 10px;
+		}
+		.rustdoc:not(.src) .doc-sidebar-title {
+			grid-area: sidebar-title;
+			background: var(--sidebar-background-color);
+			position: sticky;
+			top: 0;
+		}
+		.rustdoc:not(.src) .sidebar-crate {
+			margin-bottom: 0.5rem;
+		}
+		.rustdoc:not(.src) #TOC,
+		.rustdoc:not(.src) #CrateNav {
+			grid-area: sidebar-toc;
+			background: var(--main-background-color);
+			padding-left: 0;
+		}
+		.rustdoc:not(.src) #CrateNav {
+			grid-area: sidebar-cratenav;
+			align-self: middle;
+		}
+		.rustdoc:not(.src) #ModNav {
+			grid-area: sidebar-modnav;
+			background: var(--sidebar-background-color);
+			padding-left: 0;
+		}
+		.rustdoc:not(.src) #ModNav .in-crate {
+			display: none;
+		}
+		.rustdoc:not(.src) #TOC section,
+		.rustdoc:not(.src) #ModNav section {
+			position: sticky;
+			top: 0;
+			bottom: 0;
+			overflow-y: scroll;
+			overscroll-behavior: contain;
+			max-height: 100vh;
+			padding-left: 24px;
+		}
+		.rustdoc:not(.src) #TOC .location,
+		.rustdoc:not(.src) #ModNav h2 {
+			margin-top: 0;
+		}
+		.rustdoc:not(.src) #ModNav section {
+			top: calc(64px + 0.75rem);
+			max-height: calc(100vh - 64px - 0.75rem);
+			background: var(--sidebar-background-color);
+			border-top: solid 1px var(--border-color);
+		}
+		.rustdoc:not(.src) #TOC section {
+			max-height: calc(100vh - 0.5rem);
+			top: 0.25rem;
+			margin: 0 var(--desktop-grid-column-gap) var(--desktop-grid-column-gap) 0;
+			border: solid 1px var(--border-color);
+			padding: 0.25rem;
+		}
+		.rustdoc:not(.src) #CrateNav .block:last-child,
+		.rustdoc:not(.src) #TOC .block:last-child {
+			margin-bottom: 0;
+		}
+		.rustdoc:not(.src) #CrateNav a:hover,
+		.rustdoc:not(.src) #TOC a:hover {
+			background-color: var(--sidebar-background-color);
+		}
+	}
+}
+
 /* Make sure all the buttons line wrap at the same time */
 @media (max-width: 850px) {
 	#search-tabs .count {
diff --git a/src/librustdoc/html/static/js/main.js b/src/librustdoc/html/static/js/main.js
index 3de40b6d595bb..65bb981c1e07c 100644
--- a/src/librustdoc/html/static/js/main.js
+++ b/src/librustdoc/html/static/js/main.js
@@ -460,7 +460,7 @@ function preLoadCss(cssUrl) {
         if (!window.SIDEBAR_ITEMS) {
             return;
         }
-        const sidebar = document.getElementById("ModNav");
+        const sidebar = document.querySelector("#ModNav section");
 
         /**
          * Append to the sidebar a "block" of links - a heading along with a list (`<ul>`) of items.
@@ -496,11 +496,12 @@ function preLoadCss(cssUrl) {
                 }
                 const link = document.createElement("a");
                 link.href = path;
-                if (path === current_page) {
-                    link.className = "current";
-                }
                 link.textContent = name;
                 const li = document.createElement("li");
+                if (link.href.toString() === current_page) {
+                    link.className = "current";
+                    li.className = "current";
+                }
                 li.appendChild(link);
                 ul.appendChild(li);
             }
@@ -845,7 +846,7 @@ function preLoadCss(cssUrl) {
         if (!window.ALL_CRATES) {
             return;
         }
-        const sidebarElems = document.getElementById("ModNav");
+        const sidebarElems = document.querySelector("#ModNav section");
         if (!sidebarElems) {
             return;
         }
@@ -1511,6 +1512,15 @@ href="https://doc.rust-lang.org/${channel}/rustdoc/read-documentation/search.htm
     // At half-way past the minimum size, vanish the sidebar entirely
     const SIDEBAR_VANISH_THRESHOLD = SIDEBAR_MIN / 2;
 
+    // When running in grid layout mode, we have to change sizes
+    // on the parent element. Otherwise, we can resize the sidebar
+    // independently.
+    //
+    // This is less bad than it otherwise would be, since if you are in grid
+    // mode, resizing the sidebar will resize the floating TOC, not the huge
+    // content area.
+    let gridMode = window.getComputedStyle(document.querySelector(".rustdoc")).display === "grid";
+
     // Toolbar button to show the sidebar.
     //
     // On small, "mobile-sized" viewports, it's not persistent and it
@@ -1631,6 +1641,9 @@ href="https://doc.rust-lang.org/${channel}/rustdoc/read-documentation/search.htm
             updateLocalStorage("desktop-sidebar-width", size);
             sidebar.style.setProperty("--desktop-sidebar-width", size + "px");
             resizer.style.setProperty("--desktop-sidebar-width", size + "px");
+            if (gridMode) {
+                document.documentElement.style.setProperty("--desktop-sidebar-width", size + "px");
+            }
         }
     }
 
@@ -1682,6 +1695,7 @@ href="https://doc.rust-lang.org/${channel}/rustdoc/read-documentation/search.htm
         if (window.innerWidth < RUSTDOC_MOBILE_BREAKPOINT) {
             return;
         }
+        gridMode = window.getComputedStyle(document.querySelector(".rustdoc")).display === "grid";
         stopResize();
         if (desiredSidebarSize >= (window.innerWidth - BODY_MIN)) {
             changeSidebarSize(window.innerWidth - BODY_MIN);
diff --git a/src/librustdoc/html/templates/page.html b/src/librustdoc/html/templates/page.html
index e5bb8e6d19cec..b86008b9ed8d3 100644
--- a/src/librustdoc/html/templates/page.html
+++ b/src/librustdoc/html/templates/page.html
@@ -91,22 +91,24 @@
     {% endif %}
     <nav class="sidebar"> {# #}
         {% if page.css_class != "src" %}
-        <div class="sidebar-crate">
-            {% if !layout.logo.is_empty() || page.rust_logo %}
-            <a class="logo-container" href="{{page.root_path|safe}}{{display_krate_with_trailing_slash|safe}}index.html"> {# #}
-                {% if page.rust_logo %}
-                    <img class="rust-logo" src="{{static_root_path|safe}}{{files.rust_logo_svg}}" alt="logo"> {# #}
-                {% else if !layout.logo.is_empty() %}
-                    <img src="{{layout.logo}}" alt="logo"> {# #}
+        <div class="doc-sidebar-title">
+            <div class="sidebar-crate">
+                {% if !layout.logo.is_empty() || page.rust_logo %}
+                <a class="logo-container" href="{{page.root_path|safe}}{{display_krate_with_trailing_slash|safe}}index.html"> {# #}
+                    {% if page.rust_logo %}
+                        <img class="rust-logo" src="{{static_root_path|safe}}{{files.rust_logo_svg}}" alt="logo"> {# #}
+                    {% else if !layout.logo.is_empty() %}
+                        <img src="{{layout.logo}}" alt="logo"> {# #}
+                    {% endif %}
+                </a> {# #}
                 {% endif %}
-            </a> {# #}
-            {% endif %}
-            <h2> {# #}
-                <a href="{{page.root_path|safe}}{{display_krate_with_trailing_slash|safe}}index.html">{{display_krate}}</a> {# #}
-                {% if !display_krate_version_number.is_empty() %}
-                    <span class="version">{{+ display_krate_version_number}}</span>
-                {% endif %}
-            </h2> {# #}
+                <h2> {# #}
+                    <a href="{{page.root_path|safe}}{{display_krate_with_trailing_slash|safe}}index.html">{{display_krate}}</a> {# #}
+                    {% if !display_krate_version_number.is_empty() %}
+                        <span class="version">{{+ display_krate_version_number}}</span>
+                    {% endif %}
+                </h2> {# #}
+            </div> {# #}
         </div> {# #}
         {% if !display_krate_version_extra.is_empty() %}
         <div class="version">{{+ display_krate_version_extra}}</div> {# #}
diff --git a/src/librustdoc/html/templates/sidebar.html b/src/librustdoc/html/templates/sidebar.html
index a1cbc3dacfbb5..94284874efdae 100644
--- a/src/librustdoc/html/templates/sidebar.html
+++ b/src/librustdoc/html/templates/sidebar.html
@@ -1,12 +1,13 @@
-<div class="sidebar-elems">
-    {% if is_crate %}
+{% if is_crate %}
+<div class="sidebar-elems" id="CrateNav">
         <ul class="block">
             <li><a id="all-types" href="all.html">All Items</a></li> {# #}
         </ul>
-    {% endif %}
-
-    {% if self.should_render_blocks() %}
-        <section id="TOC">
+</div>
+{% endif %}
+{% if self.should_render_blocks() %}
+<div class="sidebar-elems" id="TOC">
+        <section>
             {% if !title.is_empty() %}
             <h2 class="location"> {# #}
                 <a href="#">{{title_prefix}}{{title}}</a> {# #}
@@ -38,12 +39,14 @@ <h3> {# #}
                 {% endif %}
             {% endfor %}
         </section>
-    {% endif %}
-    <div id="ModNav">
+</div>
+{% endif %}
+<div class="sidebar-elems" id="ModNav">
+    <section>
     {% if !path.is_empty() %}
         <h2{% if parent_is_crate +%} class="in-crate"{% endif %}> {# #}
             <a href="{% if is_mod %}../{% endif %}index.html">In {{+ path}}</a> {# #}
         </h2> {# #}
     {% endif %}
-    </div> {# #}
+    </section> {# #}
 </div>
diff --git a/tests/rustdoc-gui/sidebar.goml b/tests/rustdoc-gui/sidebar.goml
index 2fa802ae24454..fc5d0ca02b232 100644
--- a/tests/rustdoc-gui/sidebar.goml
+++ b/tests/rustdoc-gui/sidebar.goml
@@ -50,7 +50,7 @@ set-local-storage: {"rustdoc-theme": "light"}
 // We reload the page so the local storage settings are being used.
 reload:
 
-assert-text: (".sidebar > .sidebar-crate > h2 > a", "test_docs")
+assert-text: (".sidebar-crate > h2 > a", "test_docs")
 // Crate root has no "location" element
 assert-count: (".sidebar .location", 0)
 assert-count: (".sidebar h2", 1)
@@ -74,7 +74,7 @@ assert-text: ("#structs + .item-table .item-name > a", "Foo")
 click: "#structs + .item-table .item-name > a"
 
 // PAGE: struct.Foo.html
-assert-count: (".sidebar .sidebar-crate", 1)
+assert-count: (".sidebar-crate", 1)
 assert-count: (".sidebar .location", 1)
 assert-count: (".sidebar h2", 3)
 // We check that there is no crate listed outside of the top level.
@@ -95,7 +95,7 @@ click: ".sidebar-elems ul.crate > li:first-child > a"
 // PAGE: lib2/index.html
 go-to: "file://" + |DOC_PATH| + "/lib2/index.html"
 assert-property: (".sidebar", {"clientWidth": "200"})
-assert-text: (".sidebar > .sidebar-crate > h2 > a", "lib2")
+assert-text: (".sidebar-crate > h2 > a", "lib2")
 assert-count: (".sidebar .location", 0)
 // We check that we have the crates list and that the "current" on is now "lib2".
 assert-text: (".sidebar-elems ul.crate > li.current > a", "lib2")
@@ -112,7 +112,7 @@ click: "#functions + .item-table .item-name > a"
 // In items containing no items (like functions or constants) and in modules, we have no
 // "location" elements. Only the crate and optional parent module.
 // This page, being directly below the crate, only has its heading.
-assert-text: (".sidebar > .sidebar-crate > h2 > a", "lib2")
+assert-text: (".sidebar-crate > h2 > a", "lib2")
 assert-count: (".sidebar .location", 0)
 assert-count: (".sidebar h2", 1)
 // We check that we don't have the crate list.
@@ -120,7 +120,7 @@ assert-false: ".sidebar-elems > .crate"
 
 go-to: "./module/index.html"
 assert-property: (".sidebar", {"clientWidth": "200"})
-assert-text: (".sidebar > .sidebar-crate > h2 > a", "lib2")
+assert-text: (".sidebar-crate > h2 > a", "lib2")
 assert-text: (".sidebar .location", "Module module")
 assert-count: (".sidebar .location", 1)
 // Module page requires three headings:
@@ -128,8 +128,8 @@ assert-count: (".sidebar .location", 1)
 //   - Module name, followed by TOC for module headings
 //   - "In crate [name]" parent pointer, followed by sibling navigation
 assert-count: (".sidebar h2", 3)
-assert-text: (".sidebar > .sidebar-elems > #ModNav > h2", "In crate lib2")
-assert-property: (".sidebar > .sidebar-elems > #ModNav > h2 > a", {
+assert-text: ("#ModNav > section > h2", "In crate lib2")
+assert-property: ("#ModNav > section > h2 > a", {
     "href": "/lib2/index.html",
 }, ENDS_WITH)
 // We check that we don't have the crate list.
@@ -137,10 +137,10 @@ assert-false: ".sidebar-elems > .crate"
 
 go-to: "./sub_module/sub_sub_module/index.html"
 assert-property: (".sidebar", {"clientWidth": "200"})
-assert-text: (".sidebar > .sidebar-crate > h2 > a", "lib2")
+assert-text: (".sidebar-crate > h2 > a", "lib2")
 assert-text: (".sidebar .location", "Module sub_sub_module")
-assert-text: (".sidebar > .sidebar-elems > #ModNav > h2", "In lib2::module::sub_module")
-assert-property: (".sidebar > .sidebar-elems > #ModNav > h2 > a", {
+assert-text: ("#ModNav > section > h2", "In lib2::module::sub_module")
+assert-property: ("#ModNav > section > h2 > a", {
     "href": "/module/sub_module/index.html",
 }, ENDS_WITH)
 // We check that we don't have the crate list.
@@ -171,14 +171,14 @@ assert-property: (".sidebar", {"clientWidth": "200"})
 
 // Checks that all.html and index.html have their sidebar link in the same place.
 go-to: "file://" + |DOC_PATH| + "/test_docs/index.html"
-store-property: (".sidebar .sidebar-crate h2 a", {
+store-property: (".sidebar-crate h2 a", {
     "clientWidth": index_sidebar_width,
     "clientHeight": index_sidebar_height,
     "offsetTop": index_sidebar_y,
     "offsetLeft": index_sidebar_x,
 })
 go-to: "file://" + |DOC_PATH| + "/test_docs/all.html"
-assert-property: (".sidebar .sidebar-crate h2 a", {
+assert-property: (".sidebar-crate h2 a", {
     "clientWidth": |index_sidebar_width|,
     "clientHeight": |index_sidebar_height|,
     "offsetTop": |index_sidebar_y|,
diff --git a/tests/rustdoc/sidebar/top-toc-html.rs b/tests/rustdoc/sidebar/top-toc-html.rs
index 6fc84c1964c38..947d27bc5d2e0 100644
--- a/tests/rustdoc/sidebar/top-toc-html.rs
+++ b/tests/rustdoc/sidebar/top-toc-html.rs
@@ -14,6 +14,6 @@
 
 // @has foo/index.html
 // User header
-// @has - '//section[@id="TOC"]/ul[@class="block top-toc"]/li/a[@href="#basic-link-and-emphasis"]' 'Basic link and emphasis'
-// @count - '//section[@id="TOC"]/ul[@class="block top-toc"]/li/a[@href="#basic-link-and-emphasis"]/em' 0
-// @count - '//section[@id="TOC"]/ul[@class="block top-toc"]/li/a[@href="#basic-link-and-emphasis"]/a' 0
+// @has - '//ul[@class="block top-toc"]/li/a[@href="#basic-link-and-emphasis"]' 'Basic link and emphasis'
+// @count - '//ul[@class="block top-toc"]/li/a[@href="#basic-link-and-emphasis"]/em' 0
+// @count - '//ul[@class="block top-toc"]/li/a[@href="#basic-link-and-emphasis"]/a' 0
diff --git a/tests/rustdoc/sidebar/top-toc-idmap.rs b/tests/rustdoc/sidebar/top-toc-idmap.rs
index ccfc7336e9f22..0191596117c76 100644
--- a/tests/rustdoc/sidebar/top-toc-idmap.rs
+++ b/tests/rustdoc/sidebar/top-toc-idmap.rs
@@ -16,10 +16,10 @@
 
 // @has foo/index.html
 // User header
-// @has - '//section[@id="TOC"]/ul[@class="block top-toc"]/li/a[@href="#structs"]' 'Structs'
+// @has - '//ul[@class="block top-toc"]/li/a[@href="#structs"]' 'Structs'
 // @has - '//details[@class="toggle top-doc"]/div[@class="docblock"]/h2[@id="structs"]' 'Structs'
 // Built-in header
-// @has - '//section[@id="TOC"]/ul[@class="block"]/li/a[@href="#structs-1"]' 'Structs'
+// @has - '//ul[@class="block"]/li/a[@href="#structs-1"]' 'Structs'
 // @has - '//section[@id="main-content"]/h2[@id="structs-1"]' 'Structs'
 
 /// # Fields
@@ -31,12 +31,12 @@
 
 // @has foo/struct.MyStruct.html
 // User header
-// @has - '//section[@id="TOC"]/ul[@class="block top-toc"]/li/a[@href="#fields-1"]' 'Fields'
+// @has - '//ul[@class="block top-toc"]/li/a[@href="#fields-1"]' 'Fields'
 // @has - '//details[@class="toggle top-doc"]/div[@class="docblock"]/h2[@id="fields-1"]' 'Fields'
 // Only one level of nesting
-// @count - '//section[@id="TOC"]/ul[@class="block top-toc"]//a' 2
+// @count - '//ul[@class="block top-toc"]//a' 2
 // Built-in header
-// @has - '//section[@id="TOC"]/h3/a[@href="#fields"]' 'Fields'
+// @has - '//*[@id="TOC"]/section/h3/a[@href="#fields"]' 'Fields'
 // @has - '//section[@id="main-content"]/h2[@id="fields"]' 'Fields'
 
 pub struct MyStruct {