src/librustdoc/html/static/js/storage.js

   1 // storage.js is loaded in the `<head>` of all rustdoc pages and doesn't
   2 // use `async` or `defer`. That means it blocks further parsing and rendering
   3 // of the page: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script.
   4 // This makes it the correct place to act on settings that affect the display of
   5 // the page, so we don't see major layout changes during the load of the page.
   6 "use strict";
   7
   8 const darkThemes = ["dark", "ayu"];
   9 window.currentTheme = document.getElementById("themeStyle");
  10 window.mainTheme = document.getElementById("mainThemeStyle");
  11
  12 // WARNING: RUSTDOC_MOBILE_BREAKPOINT MEDIA QUERY
  13 // If you update this line, then you also need to update the media query with the same
  14 // warning in rustdoc.css
  15 window.RUSTDOC_MOBILE_BREAKPOINT = 700;
  16
  17 const settingsDataset = (function() {
  18     const settingsElement = document.getElementById("default-settings");
  19     if (settingsElement === null) {
  20         return null;
  21     }
  22     const dataset = settingsElement.dataset;
  23     if (dataset === undefined) {
  24         return null;
  25     }
  26     return dataset;
  27 })();
  28
  29 function getSettingValue(settingName) {
  30     const current = getCurrentValue(settingName);
  31     if (current !== null) {
  32         return current;
  33     }
  34     if (settingsDataset !== null) {
  35         // See the comment for `default_settings.into_iter()` etc. in
  36         // `Options::from_matches` in `librustdoc/config.rs`.
  37         const def = settingsDataset[settingName.replace(/-/g,"_")];
  38         if (def !== undefined) {
  39             return def;
  40         }
  41     }
  42     return null;
  43 }
  44
  45 const localStoredTheme = getSettingValue("theme");
  46
  47 const savedHref = [];
  48
  49 // eslint-disable-next-line no-unused-vars
  50 function hasClass(elem, className) {
  51     return elem && elem.classList && elem.classList.contains(className);
  52 }
  53
  54 // eslint-disable-next-line no-unused-vars
  55 function addClass(elem, className) {
  56     if (!elem || !elem.classList) {
  57         return;
  58     }
  59     elem.classList.add(className);
  60 }
  61
  62 // eslint-disable-next-line no-unused-vars
  63 function removeClass(elem, className) {
  64     if (!elem || !elem.classList) {
  65         return;
  66     }
  67     elem.classList.remove(className);
  68 }
  69
  70 /**
  71  * Run a callback for every element of an Array.
  72  * @param {Array<?>}    arr        - The array to iterate over
  73  * @param {function(?)} func       - The callback
  74  * @param {boolean}     [reversed] - Whether to iterate in reverse
  75  */
  76 function onEach(arr, func, reversed) {
  77     if (arr && arr.length > 0 && func) {
  78         if (reversed) {
  79             const length = arr.length;
  80             for (let i = length - 1; i >= 0; --i) {
  81                 if (func(arr[i])) {
  82                     return true;
  83                 }
  84             }
  85         } else {
  86             for (const elem of arr) {
  87                 if (func(elem)) {
  88                     return true;
  89                 }
  90             }
  91         }
  92     }
  93     return false;
  94 }
  95
  96 /**
  97  * Turn an HTMLCollection or a NodeList into an Array, then run a callback
  98  * for every element. This is useful because iterating over an HTMLCollection
  99  * or a "live" NodeList while modifying it can be very slow.
 100  * https://developer.mozilla.org/en-US/docs/Web/API/HTMLCollection
 101  * https://developer.mozilla.org/en-US/docs/Web/API/NodeList
 102  * @param {NodeList<?>|HTMLCollection<?>} lazyArray  - An array to iterate over
 103  * @param {function(?)}                   func       - The callback
 104  * @param {boolean}                       [reversed] - Whether to iterate in reverse
 105  */
 106 function onEachLazy(lazyArray, func, reversed) {
 107     return onEach(
 108         Array.prototype.slice.call(lazyArray),
 109         func,
 110         reversed);
 111 }
 112
 113 function updateLocalStorage(name, value) {
 114     try {
 115         window.localStorage.setItem("rustdoc-" + name, value);
 116     } catch (e) {
 117         // localStorage is not accessible, do nothing
 118     }
 119 }
 120
 121 function getCurrentValue(name) {
 122     try {
 123         return window.localStorage.getItem("rustdoc-" + name);
 124     } catch (e) {
 125         return null;
 126     }
 127 }
 128
 129 function switchTheme(styleElem, mainStyleElem, newThemeName, saveTheme) {
 130     // If this new value comes from a system setting or from the previously
 131     // saved theme, no need to save it.
 132     if (saveTheme) {
 133         updateLocalStorage("theme", newThemeName);
 134     }
 135
 136     if (savedHref.length === 0) {
 137         onEachLazy(document.getElementsByTagName("link"), el => {
 138             savedHref.push(el.href);
 139         });
 140     }
 141     const newHref = savedHref.find(url => {
 142         const m = url.match(/static\.files\/(.*)-[a-f0-9]{16}\.css$/);
 143         if (m && m[1] === newThemeName) {
 144             return true;
 145         }
 146         const m2 = url.match(/\/([^/]*)\.css$/);
 147         if (m2 && m2[1].startsWith(newThemeName)) {
 148             return true;
 149         }
 150     });
 151     if (newHref && newHref !== styleElem.href) {
 152         styleElem.href = newHref;
 153     }
 154 }
 155
 156 // This function is called from "main.js".
 157 // eslint-disable-next-line no-unused-vars
 158 function useSystemTheme(value) {
 159     if (value === undefined) {
 160         value = true;
 161     }
 162
 163     updateLocalStorage("use-system-theme", value);
 164
 165     // update the toggle if we're on the settings page
 166     const toggle = document.getElementById("use-system-theme");
 167     if (toggle && toggle instanceof HTMLInputElement) {
 168         toggle.checked = value;
 169     }
 170 }
 171
 172 const updateSystemTheme = (function() {
 173     if (!window.matchMedia) {
 174         // fallback to the CSS computed value
 175         return () => {
 176             const cssTheme = getComputedStyle(document.documentElement)
 177                 .getPropertyValue("content");
 178
 179             switchTheme(
 180                 window.currentTheme,
 181                 window.mainTheme,
 182                 JSON.parse(cssTheme) || "light",
 183                 true
 184             );
 185         };
 186     }
 187
 188     // only listen to (prefers-color-scheme: dark) because light is the default
 189     const mql = window.matchMedia("(prefers-color-scheme: dark)");
 190
 191     function handlePreferenceChange(mql) {
 192         const use = theme => {
 193             switchTheme(window.currentTheme, window.mainTheme, theme, true);
 194         };
 195         // maybe the user has disabled the setting in the meantime!
 196         if (getSettingValue("use-system-theme") !== "false") {
 197             const lightTheme = getSettingValue("preferred-light-theme") || "light";
 198             const darkTheme = getSettingValue("preferred-dark-theme") || "dark";
 199
 200             if (mql.matches) {
 201                 use(darkTheme);
 202             } else {
 203                 // prefers a light theme, or has no preference
 204                 use(lightTheme);
 205             }
 206             // note: we save the theme so that it doesn't suddenly change when
 207             // the user disables "use-system-theme" and reloads the page or
 208             // navigates to another page
 209         } else {
 210             use(getSettingValue("theme"));
 211         }
 212     }
 213
 214     mql.addListener(handlePreferenceChange);
 215
 216     return () => {
 217         handlePreferenceChange(mql);
 218     };
 219 })();
 220
 221 function switchToSavedTheme() {
 222     switchTheme(
 223         window.currentTheme,
 224         window.mainTheme,
 225         getSettingValue("theme") || "light",
 226         false
 227     );
 228 }
 229
 230 if (getSettingValue("use-system-theme") !== "false" && window.matchMedia) {
 231     // update the preferred dark theme if the user is already using a dark theme
 232     // See https://github.com/rust-lang/rust/pull/77809#issuecomment-707875732
 233     if (getSettingValue("use-system-theme") === null
 234         && getSettingValue("preferred-dark-theme") === null
 235         && darkThemes.indexOf(localStoredTheme) >= 0) {
 236         updateLocalStorage("preferred-dark-theme", localStoredTheme);
 237     }
 238
 239     // call the function to initialize the theme at least once!
 240     updateSystemTheme();
 241 } else {
 242     switchToSavedTheme();
 243 }
 244
 245 if (getSettingValue("source-sidebar-show") === "true") {
 246     // At this point in page load, `document.body` is not available yet.
 247     // Set a class on the `<html>` element instead.
 248     addClass(document.documentElement, "source-sidebar-expanded");
 249 }
 250
 251 // If we navigate away (for example to a settings page), and then use the back or
 252 // forward button to get back to a page, the theme may have changed in the meantime.
 253 // But scripts may not be re-loaded in such a case due to the bfcache
 254 // (https://web.dev/bfcache/). The "pageshow" event triggers on such navigations.
 255 // Use that opportunity to update the theme.
 256 // We use a setTimeout with a 0 timeout here to put the change on the event queue.
 257 // For some reason, if we try to change the theme while the `pageshow` event is
 258 // running, it sometimes fails to take effect. The problem manifests on Chrome,
 259 // specifically when talking to a remote website with no caching.
 260 window.addEventListener("pageshow", ev => {
 261     if (ev.persisted) {
 262         setTimeout(switchToSavedTheme, 0);
 263     }
 264 });