https://github.com/rust-lang/rust http://git.dreamy.place/mirrors/rust/atom?h=1.77.0 2023-12-15T10:51:23+00:00 2023-12-15T10:51:23+00:00 Guillaume Gomez guillaume1.gomez@gmail.com 2023-12-15T10:51:23+00:00 urn:sha1:f8b92697a1c444eea01ae9e723c40a35e42ad42c 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? 2023-11-25T19:33:04+00:00 Michael Howell michael@notriddle.com 2023-11-25T19:20:03+00:00 urn:sha1:bdcf91605caf75969919ae366e5e0561dcd85ea5 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 2023-10-11T17:26:36+00:00 Michael Howell michael@notriddle.com 2023-09-08T01:45:24+00:00 urn:sha1:0983438faa0431eb392be1d8ea9761fe4b1e90e2 2023-09-08T10:08:42+00:00 Guillaume Gomez guillaume.gomez@huawei.com 2023-09-08T09:09:55+00:00 urn:sha1:6ec8d71f9b4160f6cf6b98eaafdb7133486b43b5 2023-04-21T23:42:23+00:00 Michael Howell michael@notriddle.com 2023-04-21T23:28:05+00:00 urn:sha1:5cefe75436e18ed54a78cd883f00aacc50ce2f4f 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 2023-04-06T23:25:38+00:00 Michael Howell michael@notriddle.com 2023-04-06T21:53:29+00:00 urn:sha1:815f5bbcc53dbb40c11127f26080e0ad9b7dc935 * 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. 2023-01-30T16:50:09+00:00 Matthias Krüger matthias.krueger@famsik.de 2023-01-30T16:50:09+00:00 urn:sha1:d1320a542f0b27e060d19a87571e2e499b2d304a 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".) 2023-01-30T07:36:52+00:00 Roy Wellington Ⅳ cactus_hugged@yahoo.com 2023-01-21T23:21:43+00:00 urn:sha1:727a1fd1945685f21d4d2b1d86dbf6429372f3ef 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".) 2023-01-23T22:08:33+00:00 Michael Howell michael@notriddle.com 2023-01-23T17:46:40+00:00 urn:sha1:1c41b4d5aced0f7d9f692efde53e896a234c7f48 2023-01-23T22:08:33+00:00 Michael Howell michael@notriddle.com 2023-01-23T17:44:01+00:00 urn:sha1:5dd87c58aa8f9628eb8da9ad71f9c6488d409853 * 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.