| Age | Commit message (Collapse) | Author | Lines |
|---|
|
rustdoc: allow resizing the sidebar / hiding the top bar
Fixes #97306
Preview: http://notriddle.com/rustdoc-html-demo-4/sidebar-resize/std/index.html
## Summary
This feature adds:
1. A checkbox to the Settings popover to hide the persistent navigation bar (the sidebar on large viewports and the top bar on small ones).
2. On large viewports, it adds a resize handle to the persistent sidebar. Resizing it into nothing is equivalent to turning off the persistent navigation bar checkbox in Settings.
3. If the navigation bar is hidden, a toolbar button to the left of the search appears. Clicking it brings the navigation bar back.
## Motivation
While "mobile mode" is definitely a good default, it's not the only reason people have wanted to hide the sidebar:
* Some people use tiling window managers, and don't like rustdoc's current breakpoints. Changing the breakpoints might help with that, but there's no perfect solution, because there's a gap between "huge screen" and "smartphone" where reasonable people can disagree about whether it makes sense for the sidebar to be on-screen. https://github.com/rust-lang/rust/issues/97306
* Some people ask for ways to reduce on-screen clutter because it makes it easier to focus. There's not a media query for that (and if there was, privacy-conscious users would turn it off). https://github.com/rust-lang/rust/issues/59829
This feature is designed to avoid these problems. Resizing the sidebar especially helps, because it provides a way to hide the sidebar without adding a new top-level button (which would add clutter), and it provides a way to make rustdoc play nicer in complex, custom screen layouts.
## Guide and Reference-level explanation
On a desktop or laptop with a mouse, resize the sidebar by dragging its right edge.
On any browser, including mobile phones, the sticky top bar or side bar can be hidden from the Settings area (the button with the cog wheel, next to the search bar). When it's hidden, a convenient button will appear on the search bar's left.
## Drawbacks
This adds more JavaScript code to the render blocking area.
## Rationale and alternatives
The most obvious way to allow people to hide the sidebar would have been to let them "manually enter mobile mode." The upside is that it's a feature we already have. The downside is that it's actually really hard to come up with a terse description. Is it:
* A Setting that forces desktop viewers to always have the mobile-style top bar? If so, how do we label it? Should it be visible on mobile, and, if so, does it just not do anything?
* A persistent hide/show sidebar button, present on desktop, just like on mobile? That's clutter that I'd like to avoid.
## Prior art
* The new file browser in GitHub uses a similar divider with a mouse-over indicator
* mdBook and macOS Finder both allow you to resize the sidebar to nothing as a gesture to hide it
* https://www.nngroup.com/articles/drag-drop/
## Future possibilities
https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Table.20of.20contents proposes a new, second sidebar (a table of contents). How should it fit in with this feature? Should it be resizeable? Hideable? Can it be accessed on mobile?
|
|
According to [MDN], this function is compatible with:
* Chrome 16 and Edge 12
* Firefox 9
* Safari 1.1 and iOS Safari 1
These browsers are well within our [support matrix], which requires
compatibility with Chrome 118, Firefox 115, Safari 17, and Edge 119.
[MDN]: https://developer.mozilla.org/en-US/docs/Web/API/Node/contains#browser_compatibility
[support matrix]: https://browsersl.ist/#q=last+2+Chrome+versions%2C+last+1+Firefox+version%2C+Firefox+ESR%2C+last+1+Safari+version%2C+last+1+iOS+version%2C+last+1+Edge+version%2C+last+1+UCAndroid+version
|
|
|
|
|
|
This code was added in 9dc5dfb97504c538bc72f367a77bb9f714c30097
and 704050da2334c465784954d81c8990c4bc7a92c5 because the browser-
native checkbox was `display: none`, breaking native keyboard
accessibility.
The native checkbox is now merely `appearance: none`, which does
not turn off [behavior semantics], so JavaScript to
reimplement it isn't needed any more.
[behavior semantics]: https://w3c.github.io/csswg-drafts/css-ui/#appearance-semantics
|
|
* Stop checking `func` in `onEach`. It's always hard-coded right
at the call site, so there's no point.
* Use the ternary operator in a few spots where it makes sense.
* No point in making `onEach` store `arr.length` in a variable if
it's only used once anyway.
|
|
Keep all theme-updating logic together
Prior to this PR, if the page is restored from the browser bfcache¹, we call `switchToSavedTheme`. But `switchToSavedTheme` never looks at the `use-system-theme` preference. Further, if it can't find a saved theme, it will fall back to the default of "light".
For a user with cookies disabled² whose preferred color scheme is dark, this means the theme will wobble back and forth between dark and light. The sequence that occurs is,
1. The page is loaded. During a page load, we consult `use-system-theme`: as cookies are disabled, this preference is unset. The default is true.
Because the default is true, we look at the preferred color scheme: for our example user, that's "dark". **The page theme is set to dark.** We'll attempt to store these preferences in localStorage, but fail due to cookies being disabled.
2. The user navigates through the docs. Subsequent page loads happen, and the same process in step 1 recurs. Previous pages are (potentially) put into the bfcache.
3. The user navigates backwards/forwards, causing a page in bfcache to be pulled out of cache. The `pageShow` event handler is triggered. However, this calls `switchToSavedTheme`: this doesn't consider the system theme, as noted above. Instead, it only looks for a saved theme. However, with cookies disabled, there is none. It defaults to light. **The page theme is set to light!** The user wonders why the dark theme is lost.
There are effectively two functions trying to determine and apply the correct theme: `updateSystemTheme` and `switchToSavedTheme`. Thus, we merge them into just one: `updateTheme`. This function contains all the logic for determining the correct theme, and is called in all circumstances where we need to set the theme:
* The initial page load
* If the browser preferred color scheme (i.e., light/dark mode) is changed
* If the page is restored from bfcache
* If the user updates the theme preferences (i.e., in `settings.js`)
Fixes https://github.com/rust-lang/rust/issues/94250.
¹bfcache: https://web.dev/bfcache/ The bfcache is used to sleep a page, if the user navigates away from it, and to restore it from cache if the user returns to it.
²Note that the browser preference that enables/disables cookies really controls many forms of storage. The same preference thus also affects localStorage. (This is so a normal browser user doesn't need to understand the distinction between "cookies" and "localStorage".)
|
|
Prior to this PR, if the page is restored from the browser bfcache¹, we
call `switchToSavedTheme`. But `switchToSavedTheme` never looks at the
`use-system-theme` preference. Further, if it can't find a saved theme,
it will fall back to the default of "light".
For a user with cookies disabled² whose preferred color scheme is dark,
this means the theme will wobble back and forth between dark and light.
The sequence that occurs is,
1. The page is loaded. During a page load, we consult
`use-system-theme`: as cookies are disabled, this preference is
unset. The default is true.
Because the default is true, we look at the preferred color scheme:
for our example user, that's "dark". **The page theme is set to
dark.** We'll attempt to store these preferences in localStorage, but
fail due to cookies being disabled.
2. The user navigates through the docs. Subsequent page loads happen,
and the same process in step 1 recurs. Previous pages are
(potentially) put into the bfcache.
3. The user navigates backwards/forwards, causing a page in bfcache to
be pulled out of cache. The `pageShow` event handler is triggered.
However, this calls `switchToSavedTheme`: this doesn't consider the
system theme, as noted above. Instead, it only looks for a saved
theme. However, with cookies disabled, there is none. It defaults to
light. **The page theme is set to light!** The user wonders why the
dark theme is lost.
There are effectively two functions trying to determine and apply the
correct theme: `updateSystemTheme` and `switchToSavedTheme`. Thus, we
merge them into just one: `updateTheme`. This function contains all the
logic for determining the correct theme, and is called in all
circumstances where we need to set the theme:
* The initial page load
* If the browser preferred color scheme (i.e., light/dark mode) is
changed
* If the page is restored from bfcache
* If the user updates the theme preferences (i.e., in `settings.js`)
Fixes #94250.
¹bfcache: https://web.dev/bfcache/ The bfcache is used to sleep a page,
if the user navigates away from it, and to restore it from cache if the
user returns to it.
²Note that the browser preference that enables/disables cookies really
controls many forms of storage. The same preference thus also affects
localStorage. (This is so a normal browser user doesn't need to
understand the distinction between "cookies" and "localStorage".)
|
|
|
|
* Changes the class names so that they all start with `setting-`.
That should make it harder to accidentally use a setting class outside
the settings popover, where loading the CSS might accidentally change
the styles of something unrelated.
* Get rid of an unnecessary wrapper DIV around the radio button line.
* Simplify CSS selectors by making the DOM easier and more intuitive
to target.
|
|
|
|
This swaps things around so that the class that gets used more often has
the shorter name.
|
|
This commit fixes a few inconsistencies and erratic behavior from the
notable traits, settings, and sidebar popups:
* It makes it so that pressing Escape closes the mobile sidebar.
This is a bit difficult to do on iPhone, but on other setups like
desktop tiling window managers, it's easy and makes sense.
* It makes sure that pressing escape while a notable trait popover is
open focuses the popover's toggle button, instead of leaving nothing
focused, since that makes more sense with keyboard navigation. Clicking
the settings, help, or sidebar buttons, however, will not focus the
notable trait popover toggle button.
* It ensures that notable trait and settings popovers are exclusive
with the mobile sidebar. Nothing should ever overlap a popover, and
there should never be more than one popover open at once.
|
|
|
|
The switch is designed to give the application a "physical" feel, but
nothing else in here really followed through. They didn't support the
"flick" gesture that real iOS switches support, and the radio
buttons that were also used in Rustdoc Settings were a more "classic"
form element anyway.
Also, while "switches" are the exclusive toggle design on iOS (since
[Apple HIG] reserves checkboxes for Mac only), the [Google Material]
guidelines say that lists of switches are bad, and you should just use
check boxes.
[Apple HIG]: https://developer.apple.com/design/human-interface-guidelines/components/selection-and-input/toggles
[Google Material]: https://m3.material.io/components/checkbox/guidelines#6902f23d-ceba-4b19-ae3b-b78b9b01d185
|
|
All static files used by rustdoc are now stored in static.files/ and
include a hash of their contents. They no longer include the contents of
the --resource-suffix flag. This clarifies caching semantics. Anything
in static.files can use Cache-Control: immutable because any updates
will show up as a new URL.
Invocation-specific files like crates-NN.js, search-index-NN.js,
and sidebar-items-NN.js still get the resource suffix.
The --disable-minification flag is removed because it would vary the
output of static files based on invocation flags. Instead, for
rustdoc development purposes it's preferable to symlink static files
to a non-minified copy for quick iteration.
|
|
|
|
|
|
|
|
|
|
|
|
Add more eslint rules
This PR adds more eslint rules. Here are the explanations for each of them:
* [space-infix-ops](https://eslint.org/docs/rules/space-infix-ops)
* [space-before-function-paren](https://eslint.org/docs/rules/space-before-function-paren)
* [space-before-blocks](https://eslint.org/docs/rules/space-before-blocks)
* [comma-dangle](https://eslint.org/docs/rules/comma-dangle)
* [comma-style](https://eslint.org/docs/rules/comma-style)
* [max-len](https://eslint.org/docs/rules/max-len)
* [eol-last](https://eslint.org/docs/rules/eol-last)
r? `@notriddle`
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
r=jsha
Improve settings loading strategy
I learned about this thanks to ```@jsha``` who suggested this approach:
It improves the settings loading strategy by loading CSS and JS at the same time to prevent the style to be applied afterwards on slow connections.
r? ```@jsha```
|
|
Add rotation animation on settings button when loading
As discussed, I added an animation when the settings JS file is loading (I voluntarily made the timeout at the end of the `settings.js` super long so we can see what the animation looks like):
https://user-images.githubusercontent.com/3050060/166693243-816a08b7-5e39-4142-acd3-686ad9950d8e.mp4
r? ````@jsha````
|
|
prevent the style to be applied afterwards on slow connections
|
|
|
|
|
|
Fix lint
Fix main.js
Restore anonymous functions
Fix
Fix more
|
|
* Improve code.
* Fix some documentation argument types.
* Make settings order the same as before this PR.
* Change timeout to 0 so that browser will render it as fast as possible.
|
|
|
|
|
|
|
|
|
|
This reduces the number of clicks required to change theme.
Also, simplify the UI a bit (remove setting grouping), and add a "Back"
link close to the settings icon.
|
|
|
|
|
