Rollup merge of #96958 - GuillaumeGomez:settings-menu-display, r=jsha

Improve settings menu display and remove theme menu

We talked about improving the settings menu and we mentioned that firefox pocket was a nice inspiration so I implemented it. The result looks like this:

![Screenshot from 2022-05-11 23-59-53](https://user-images.githubusercontent.com/3050060/167954743-438c0a06-4628-478c-bf0c-d20313c1fdfc.png)

You can test it [here](https://rustdoc.crud.net/imperio/settings-menu-display/doc/foo/index.html).

Only question I have is: should I re-assign the shortcut `T` to this setting menu now that the theme menu is gone? For now I simply removed it.

Important to be noted: the full settings page (at `settings.html`) is still rendered the same as currently.

r? ``@jsha``
This commit is contained in:
Matthias Krüger 2022-05-15 08:10:42 +02:00 committed by GitHub
commit 7bf43c3931
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 152 additions and 276 deletions

View File

@ -59,15 +59,8 @@ or the current item whose documentation is being displayed.
## The Theme Picker and Search Interface
When viewing `rustdoc`'s output in a browser with JavaScript enabled,
a dynamic interface appears at the top of the page.
To the left is the theme picker, denoted with a paint-brush icon,
and the search interface, help screen, and options appear to the right of that.
### The Theme Picker
Clicking on the theme picker provides a list of themes -
by default `ayu`, `light`, and `dark` -
which are available for viewing.
a dynamic interface appears at the top of the page composed of the search
interface, help screen, and options.
### The Search Interface
@ -91,12 +84,16 @@ When typing in the search bar, you can prefix your search term with a type
followed by a colon (such as `mod:`) to restrict the results to just that
kind of item. (The available items are listed in the help popup.)
### Changing displayed theme
You can change the displayed theme by opening the settings menu (the gear
icon in the upper right) and then pick a new one from there.
### Shortcuts
Pressing `S` while focused elsewhere on the page will move focus to the
search bar, and pressing `?` shows the help screen,
which includes all these shortcuts and more.
Pressing `T` focuses the theme picker.
When the search results are focused,
the left and right arrows move between tabs and the up and down arrows move

View File

@ -109,8 +109,9 @@ rustdoc --extend-css custom.css src/lib.rs
A good example of using this feature to create a dark theme is documented [on
this blog]. Just remember, dark theme is already included in the rustdoc output
by clicking on the paintbrush. Adding additional options to the themes are
as easy as creating a custom theme `.css` file and using the following syntax:
by clicking on the gear icon in the upper right. Adding additional options to the
themes are as easy as creating a custom theme `.css` file and using the following
syntax:
```bash
rustdoc --theme awesome.css src/lib.rs

View File

@ -1448,8 +1448,6 @@ fn init_id_map() -> FxHashMap<Cow<'static, str>, usize> {
// used in tera template files).
map.insert("mainThemeStyle".into(), 1);
map.insert("themeStyle".into(), 1);
map.insert("theme-picker".into(), 1);
map.insert("theme-choices".into(), 1);
map.insert("settings-menu".into(), 1);
map.insert("help-button".into(), 1);
map.insert("main-content".into(), 1);

View File

@ -238,7 +238,6 @@ pub(super) fn write_shared(
write_toolchain("favicon-16x16.png", static_files::RUST_FAVICON_PNG_16)?;
write_toolchain("favicon-32x32.png", static_files::RUST_FAVICON_PNG_32)?;
}
write_toolchain("brush.svg", static_files::BRUSH_SVG)?;
write_toolchain("wheel.svg", static_files::WHEEL_SVG)?;
write_toolchain("clipboard.svg", static_files::CLIPBOARD_SVG)?;
write_toolchain("down-arrow.svg", static_files::DOWN_ARROW_SVG)?;

View File

@ -18,7 +18,3 @@ rules.
/* The search bar and related controls don't work without JS */
display: none;
}
#theme-picker {
display: none;
}

View File

@ -1379,31 +1379,30 @@ pre.rust {
margin-bottom: 6px;
}
.theme-picker {
position: absolute;
left: -38px;
top: 4px;
}
.theme-picker button {
outline: none;
}
#settings-menu, #help-button {
margin-left: 4px;
outline: none;
}
#theme-picker, #copy-path {
#copy-path {
height: 34px;
}
#theme-picker, #settings-menu, #help-button, #copy-path {
#settings-menu > a, #help-button, #copy-path {
padding: 5px;
width: 33px;
border: 1px solid;
border-radius: 2px;
cursor: pointer;
}
#settings-menu {
padding: 0;
}
#settings-menu > a {
padding: 5px;
width: 100%;
height: 100%;
display: block;
}
@keyframes rotating {
from {
@ -1413,9 +1412,33 @@ pre.rust {
transform: rotate(360deg);
}
}
#settings-menu.rotate img {
#settings-menu.rotate > a img {
animation: rotating 2s linear infinite;
}
#settings-menu #settings {
position: absolute;
right: 0;
z-index: 1;
display: block;
margin-top: 7px;
border-radius: 3px;
border: 1px solid;
}
#settings-menu #settings .setting-line {
margin: 0.6em;
}
/* This rule is to draw the little arrow connecting the settings menu to the gear icon. */
#settings-menu #settings::before {
content: '';
position: absolute;
right: 11px;
border: solid;
border-width: 1px 1px 0 0;
display: inline-block;
padding: 4px;
transform: rotate(-45deg);
top: -5px;
}
#help-button {
font-family: "Fira Sans", Arial, sans-serif;
@ -1838,12 +1861,6 @@ details.rustdoc-toggle[open] > summary.hideme::after {
margin-left: 32px;
}
/* Space is at a premium on mobile, so remove the theme-picker icon. */
#theme-picker {
display: none;
width: 0;
}
.content {
margin-left: 0px;
}

View File

@ -5,7 +5,7 @@ Original by Dempfi (https://github.com/dempfi/ayu)
/* General structure and fonts */
body {
body, #settings-menu #settings, #settings-menu #settings::before {
background-color: #0f1419;
color: #c5c5c5;
}
@ -531,16 +531,20 @@ kbd {
box-shadow: inset 0 -1px 0 #5c6773;
}
#theme-picker, #settings-menu, #help-button {
#settings-menu > a, #help-button {
border-color: #5c6773;
background-color: #0f1419;
color: #fff;
}
#theme-picker > img, #settings-menu > img {
#settings-menu > a img {
filter: invert(100);
}
#settings-menu #settings, #settings-menu #settings::before {
border-color: #5c6773;
}
#copy-path {
color: #fff;
}
@ -551,8 +555,7 @@ kbd {
filter: invert(100%);
}
#theme-picker:hover, #theme-picker:focus,
#settings-menu:hover, #settings-menu:focus,
#settings-menu > a:hover, #settings-menu > a:focus,
#help-button:hover, #help-button:focus {
border-color: #e0e0e0;
}
@ -570,12 +573,6 @@ kbd {
background-color: rgba(110, 110, 110, 0.33);
}
@media (max-width: 700px) {
#theme-picker {
background: #0f1419;
}
}
.search-results .result-name span.alias {
color: #c5c5c5;
}

View File

@ -1,4 +1,4 @@
body {
body, #settings-menu #settings, #settings-menu #settings::before {
background-color: #353535;
color: #ddd;
}
@ -408,18 +408,21 @@ kbd {
box-shadow: inset 0 -1px 0 #c6cbd1;
}
#theme-picker, #settings-menu, #help-button {
#settings-menu > a, #help-button {
border-color: #e0e0e0;
background: #f0f0f0;
color: #000;
}
#theme-picker:hover, #theme-picker:focus,
#settings-menu:hover, #settings-menu:focus,
#settings-menu > a:hover, #settings-menu > a:focus,
#help-button:hover, #help-button:focus {
border-color: #ffb900;
}
#settings-menu #settings, #settings-menu #settings::before {
border-color: #d2d2d2;
}
#copy-path {
color: #999;
}
@ -443,12 +446,6 @@ kbd {
background-color: #4e4e4e;
}
@media (max-width: 700px) {
#theme-picker {
background: #f0f0f0;
}
}
.search-results .result-name span.alias {
color: #fff;
}

View File

@ -1,6 +1,6 @@
/* General structure and fonts */
body {
body, #settings-menu #settings, #settings-menu #settings::before {
background-color: white;
color: black;
}
@ -394,17 +394,20 @@ kbd {
box-shadow: inset 0 -1px 0 #c6cbd1;
}
#theme-picker, #settings-menu, #help-button {
#settings-menu > a, #help-button {
border-color: #e0e0e0;
background-color: #fff;
}
#theme-picker:hover, #theme-picker:focus,
#settings-menu:hover, #settings-menu:focus,
#settings-menu > a:hover, #settings-menu > a:focus,
#help-button:hover, #help-button:focus {
border-color: #717171;
}
#settings-menu #settings, #settings-menu #settings::before {
border-color: #DDDDDD;
}
#copy-path {
color: #999;
}
@ -428,12 +431,6 @@ kbd {
background-color: #eee;
}
@media (max-width: 700px) {
#theme-picker {
background: #fff;
}
}
.search-results .result-name span.alias {
color: #000;
}

View File

@ -1,7 +1,6 @@
// Local js definitions:
/* global addClass, getSettingValue, hasClass, searchState */
/* global onEach, onEachLazy, removeClass */
/* global switchTheme, useSystemTheme */
"use strict";
@ -109,21 +108,11 @@ function getVirtualKey(ev) {
return String.fromCharCode(c);
}
const THEME_PICKER_ELEMENT_ID = "theme-picker";
const THEMES_ELEMENT_ID = "theme-choices";
const MAIN_ID = "main-content";
const SETTINGS_BUTTON_ID = "settings-menu";
const ALTERNATIVE_DISPLAY_ID = "alternative-display";
const NOT_DISPLAYED_ID = "not-displayed";
function getThemesElement() {
return document.getElementById(THEMES_ELEMENT_ID);
}
function getThemePickerElement() {
return document.getElementById(THEME_PICKER_ELEMENT_ID);
}
function getSettingsButton() {
return document.getElementById(SETTINGS_BUTTON_ID);
}
@ -133,74 +122,10 @@ function getNakedUrl() {
return window.location.href.split("?")[0].split("#")[0];
}
function showThemeButtonState() {
const themePicker = getThemePickerElement();
const themeChoices = getThemesElement();
themeChoices.style.display = "block";
themePicker.style.borderBottomRightRadius = "0";
themePicker.style.borderBottomLeftRadius = "0";
}
function hideThemeButtonState() {
const themePicker = getThemePickerElement();
const themeChoices = getThemesElement();
themeChoices.style.display = "none";
themePicker.style.borderBottomRightRadius = "3px";
themePicker.style.borderBottomLeftRadius = "3px";
}
window.hideSettings = () => {
// Does nothing by default.
};
// Set up the theme picker list.
(function () {
if (!document.location.href.startsWith("file:///")) {
return;
}
const themeChoices = getThemesElement();
const themePicker = getThemePickerElement();
const availableThemes = getVar("themes").split(",");
removeClass(themeChoices.parentElement, "hidden");
function switchThemeButtonState() {
if (themeChoices.style.display === "block") {
hideThemeButtonState();
} else {
showThemeButtonState();
}
}
function handleThemeButtonsBlur(e) {
const active = document.activeElement;
const related = e.relatedTarget;
if (active.id !== THEME_PICKER_ELEMENT_ID &&
(!active.parentNode || active.parentNode.id !== THEMES_ELEMENT_ID) &&
(!related ||
(related.id !== THEME_PICKER_ELEMENT_ID &&
(!related.parentNode || related.parentNode.id !== THEMES_ELEMENT_ID)))) {
hideThemeButtonState();
}
}
themePicker.onclick = switchThemeButtonState;
themePicker.onblur = handleThemeButtonsBlur;
availableThemes.forEach(item => {
const but = document.createElement("button");
but.textContent = item;
but.onclick = () => {
switchTheme(window.currentTheme, window.mainTheme, item, true);
useSystemTheme(false);
};
but.onblur = handleThemeButtonsBlur;
themeChoices.appendChild(but);
});
}());
/**
* This function inserts `newNode` after `referenceNode`. It doesn't work if `referenceNode`
* doesn't have a parent node.
@ -512,7 +437,7 @@ function loadCss(cssFileName) {
ev.preventDefault();
}
searchState.defocus();
hideThemeButtonState();
window.hideSettings();
}
const disableShortcuts = getSettingValue("disable-shortcuts") === "true";
@ -522,8 +447,6 @@ function loadCss(cssFileName) {
return;
}
let themePicker;
if (document.activeElement.tagName === "INPUT") {
switch (getVirtualKey(ev)) {
case "Escape":
@ -553,64 +476,9 @@ function loadCss(cssFileName) {
displayHelp(true, ev);
break;
case "t":
case "T":
displayHelp(false, ev);
ev.preventDefault();
themePicker = getThemePickerElement();
themePicker.click();
themePicker.focus();
break;
default:
if (getThemePickerElement().parentNode.contains(ev.target)) {
handleThemeKeyDown(ev);
}
}
}
}
function handleThemeKeyDown(ev) {
const active = document.activeElement;
const themes = getThemesElement();
switch (getVirtualKey(ev)) {
case "ArrowUp":
ev.preventDefault();
if (active.previousElementSibling && ev.target.id !== THEME_PICKER_ELEMENT_ID) {
active.previousElementSibling.focus();
} else {
showThemeButtonState();
themes.lastElementChild.focus();
}
break;
case "ArrowDown":
ev.preventDefault();
if (active.nextElementSibling && ev.target.id !== THEME_PICKER_ELEMENT_ID) {
active.nextElementSibling.focus();
} else {
showThemeButtonState();
themes.firstElementChild.focus();
}
break;
case "Enter":
case "Return":
case "Space":
if (ev.target.id === THEME_PICKER_ELEMENT_ID && themes.style.display === "none") {
ev.preventDefault();
showThemeButtonState();
themes.firstElementChild.focus();
}
break;
case "Home":
ev.preventDefault();
themes.firstElementChild.focus();
break;
case "End":
ev.preventDefault();
themes.lastElementChild.focus();
break;
// The escape key is handled in handleEscape, not here,
// so that pressing escape will close the menu even if it isn't focused
}
}
@ -1006,7 +874,6 @@ function loadCss(cssFileName) {
const shortcuts = [
["?", "Show this help dialog"],
["S", "Focus the search field"],
["T", "Focus the theme picker menu"],
["↑", "Move up in search results"],
["↓", "Move down in search results"],
["← / →", "Switch result tab (when results focused)"],

View File

@ -1,7 +1,7 @@
// Local js definitions:
/* global getSettingValue, getVirtualKey, updateLocalStorage, updateSystemTheme */
/* global addClass, removeClass, onEach, onEachLazy, NOT_DISPLAYED_ID */
/* global MAIN_ID, getVar, getSettingsButton, switchDisplayedElement, getNotDisplayedElem */
/* global addClass, removeClass, onEach, onEachLazy */
/* global MAIN_ID, getVar, getSettingsButton */
"use strict";
@ -206,38 +206,60 @@
];
// Then we build the DOM.
const el = document.createElement("section");
el.id = "settings";
let innerHTML = `
<div class="main-heading">
let innerHTML = "";
let elementKind = "div";
if (isSettingsPage) {
elementKind = "section";
innerHTML = `<div class="main-heading">
<h1 class="fqn">
<span class="in-band">Rustdoc settings</span>
</h1>
<span class="out-of-band">`;
if (isSettingsPage) {
innerHTML +=
"<a id=\"back\" href=\"javascript:void(0)\" onclick=\"history.back();\">Back</a>";
} else {
innerHTML += "<a id=\"back\" href=\"javascript:void(0)\" " +
"onclick=\"switchDisplayedElement(null);\">Back</a>";
<span class="out-of-band">
<a id="back" href="javascript:void(0)" onclick="history.back();">Back</a>
</span>
</div>`;
}
innerHTML += `</span>
</div>
<div class="settings">${buildSettingsPageSections(settings)}</div>`;
innerHTML += `<div class="settings">${buildSettingsPageSections(settings)}</div>`;
const el = document.createElement(elementKind);
el.id = "settings";
el.innerHTML = innerHTML;
if (isSettingsPage) {
document.getElementById(MAIN_ID).appendChild(el);
} else {
getNotDisplayedElem().appendChild(el);
el.setAttribute("tabindex", "-1");
getSettingsButton().appendChild(el);
}
return el;
}
const settingsMenu = buildSettingsPage();
function displaySettings() {
settingsMenu.style.display = "";
}
function elemIsInParent(elem, parent) {
while (elem && elem !== document.body) {
if (elem === parent) {
return true;
}
elem = elem.parentElement;
}
return false;
}
function blurHandler(event) {
const settingsButton = getSettingsButton();
if (!elemIsInParent(document.activeElement, settingsButton) &&
!elemIsInParent(event.relatedTarget, settingsButton))
{
window.hideSettings();
}
}
if (isSettingsPage) {
// We replace the existing "onclick" callback to do nothing if clicked.
getSettingsButton().onclick = function(event) {
@ -246,17 +268,27 @@
} else {
// We replace the existing "onclick" callback.
const settingsButton = getSettingsButton();
const settingsMenu = document.getElementById("settings");
window.hideSettings = function() {
settingsMenu.style.display = "none";
};
settingsButton.onclick = function(event) {
if (elemIsInParent(event.target, settingsMenu)) {
return;
}
event.preventDefault();
if (settingsMenu.parentElement.id === NOT_DISPLAYED_ID) {
switchDisplayedElement(settingsMenu);
} else {
if (settingsMenu.style.display !== "none") {
window.hideSettings();
} else {
displaySettings();
}
};
window.hideSettings = function() {
switchDisplayedElement(null);
};
settingsButton.onblur = blurHandler;
settingsButton.querySelector("a").onblur = blurHandler;
onEachLazy(settingsMenu.querySelectorAll("input"), el => {
el.onblur = blurHandler;
});
settingsMenu.onblur = blurHandler;
}
// We now wait a bit for the web browser to end re-computing the DOM...
@ -264,7 +296,7 @@
setEvents(settingsMenu);
// The setting menu is already displayed if we're on the settings page.
if (!isSettingsPage) {
switchDisplayedElement(settingsMenu);
displaySettings();
}
removeClass(getSettingsButton(), "rotate");
}, 0);

View File

@ -41,9 +41,6 @@ crate static SCRAPE_EXAMPLES_JS: &str = include_str!("static/js/scrape-examples.
crate static SCRAPE_EXAMPLES_HELP_MD: &str = include_str!("static/scrape-examples-help.md");
/// The file contents of `brush.svg`, the icon used for the theme-switch button.
crate static BRUSH_SVG: &[u8] = include_bytes!("static/images/brush.svg");
/// The file contents of `wheel.svg`, the icon used for the settings button.
crate static WHEEL_SVG: &[u8] = include_bytes!("static/images/wheel.svg");

View File

@ -108,13 +108,6 @@
{%- endif -%}
</a> {#- -#}
<nav class="sub"> {#- -#}
<div class="theme-picker hidden"> {#- -#}
<button id="theme-picker" aria-label="Pick another theme!" aria-haspopup="menu" title="themes"> {#- -#}
<img width="22" height="22" alt="Pick another theme!" {# -#}
src="{{static_root_path|safe}}brush{{page.resource_suffix}}.svg"> {#- -#}
</button> {#- -#}
<div id="theme-choices" role="menu"></div> {#- -#}
</div> {#- -#}
<form class="search-form"> {#- -#}
<div class="search-container"> {#- -#}
<span></span> {#- This empty span is a hacky fix for Safari - See #93184 -#}
@ -126,10 +119,12 @@
placeholder="Click or press S to search, ? for more options…" {# -#}
type="search"> {#- -#}
<button type="button" id="help-button" title="help">?</button> {#- -#}
<a id="settings-menu" href="{{page.root_path|safe}}settings.html" title="settings"> {#- -#}
<div id="settings-menu" tabindex="-1">
<a href="{{page.root_path|safe}}settings.html" title="settings"> {#- -#}
<img width="22" height="22" alt="Change settings" {# -#}
src="{{static_root_path|safe}}wheel{{page.resource_suffix}}.svg"> {#- -#}
</a> {#- -#}
</div>
</div> {#- -#}
</form> {#- -#}
</nav> {#- -#}

View File

@ -5,36 +5,25 @@ assert-false: "#settings"
// We now click on the settings button.
click: "#settings-menu"
wait-for: "#settings"
assert: "#main-content.hidden"
assert-css: ("#settings", {"display": "block"})
// Let's close it by clicking on the same button.
click: "#settings-menu"
assert-false: "#alternative-display #settings"
assert: "#not-displayed #settings"
assert: "#main-content:not(.hidden)"
// Let's open and then close it again with the "close settings" button.
click: "#settings-menu"
wait-for: "#alternative-display #settings"
assert: "#main-content.hidden"
click: "#back"
wait-for: "#not-displayed #settings"
assert: "#main-content:not(.hidden)"
wait-for-css: ("#settings", {"display": "none"})
// Let's check that pressing "ESCAPE" is closing it.
click: "#settings-menu"
wait-for: "#alternative-display #settings"
wait-for-css: ("#settings", {"display": "block"})
press-key: "Escape"
wait-for: "#not-displayed #settings"
assert: "#main-content:not(.hidden)"
wait-for-css: ("#settings", {"display": "none"})
// Let's click on it when the search results are displayed.
focus: ".search-input"
write: "test"
wait-for: "#alternative-display #search"
click: "#settings-menu"
wait-for: "#alternative-display #settings"
assert: "#not-displayed #search"
wait-for-css: ("#settings", {"display": "block"})
// Ensure that the search is still displayed.
wait-for: "#alternative-display #search"
assert: "#main-content.hidden"
// Now let's check the content of the settings menu.

View File

@ -12,15 +12,3 @@ assert-css: ("#help", {"display": "flex"})
assert-false: "#help.hidden"
press-key: "Escape"
assert-css: ("#help.hidden", {"display": "none"})
// Check for the themes list.
assert-css: ("#theme-choices", {"display": "none"})
press-key: "t"
assert-css: ("#theme-choices", {"display": "block"})
press-key: "t"
// We ensure that 't' hides back the menu.
assert-css: ("#theme-choices", {"display": "none"})
press-key: "t"
assert-css: ("#theme-choices", {"display": "block"})
press-key: "Escape"
// We ensure that 'Escape' hides the menu too.
assert-css: ("#theme-choices", {"display": "none"})

View File

@ -1,12 +1,21 @@
// Ensures that the theme change is working as expected.
goto: file://|DOC_PATH|/test_docs/index.html
click: "#theme-picker"
click: "#theme-choices > button:first-child"
// should be the ayu theme so let's check the color
local-storage: {"rustdoc-use-system-theme": "false", "rustdoc-theme": "dark"}
reload:
click: "#settings-menu"
wait-for: "#theme-ayu"
click: "#theme-ayu"
// should be the ayu theme so let's check the color.
wait-for-css: ("body", { "background-color": "rgb(15, 20, 25)" })
click: "#theme-choices > button:last-child"
// should be the light theme so let's check the color
assert-local-storage: { "rustdoc-theme": "ayu" }
click: "#theme-light"
// should be the light theme so let's check the color.
wait-for-css: ("body", { "background-color": "rgb(255, 255, 255)" })
assert-local-storage: { "rustdoc-theme": "light" }
click: "#theme-dark"
// Should be the dark theme so let's check the color.
wait-for-css: ("body", { "background-color": "rgb(53, 53, 53)" })
assert-local-storage: { "rustdoc-theme": "dark" }
goto: file://|DOC_PATH|/settings.html
wait-for: "#settings"