Enable resetting HTML colour scheme preferences

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>

pep_sphinx_extensions/pep_theme/static/colour_scheme.js

@@ -1,36 +1,31 @@
-const dark = document.getElementById("css-dark");
-const pygmentsNormal = document.getElementById("pyg");
-const pygmentsDark = document.getElementById("pyg-dark");
-
-const makeLight = () => {
-    dark.disabled = pygmentsDark.disabled = true
-    dark.media = pygmentsNormal.media = pygmentsDark.media = ""
-    pygmentsNormal.disabled = false
+const prefersDark = window.matchMedia("(prefers-color-scheme: dark)")
 
+const getColourScheme = () => document.documentElement.dataset.colour_scheme
+const setColourScheme = (colourScheme = getColourScheme()) => {
+    document.documentElement.dataset.colour_scheme = colourScheme
+    localStorage.setItem("colour_scheme", colourScheme)
+    setPygments(colourScheme)
 }
 
-const makeDark = () => {
-    dark.disabled = pygmentsDark.disabled = false
-    dark.media = pygmentsNormal.media = pygmentsDark.media = ""
-    pygmentsNormal.disabled = true
+// Map system theme to a cycle of steps
+const cycles = {
+    dark: ["auto", "light", "dark"], // auto (dark) → light → dark
+    light: ["auto", "dark", "light"], // auto (light) → dark → light
 }
 
-
-const toggleColourScheme = () => {
-    const colourScheme = localStorage.getItem("colour_scheme")
-    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches
-
-    if ((colourScheme === "dark") || (!colourScheme && prefersDark)) {
-        makeLight()
-        localStorage.setItem("colour_scheme", "light")
-    } else {
-        makeDark()
-        localStorage.setItem("colour_scheme", "dark")
-    }
+const nextColourScheme = (colourScheme = getColourScheme()) => {
+    const cycle = cycles[prefersDark.matches ? "dark" : "light"]
+    return cycle[(cycle.indexOf(colourScheme) + 1) % cycle.length]
 }
 
-/* set colour scheme from local storage */
-document.addEventListener("DOMContentLoaded", () => {
-    if (localStorage.getItem("colour_scheme") === "light") makeLight()
-    if (localStorage.getItem("colour_scheme") === "dark") makeDark()
-})
+const setPygments = (colourScheme = getColourScheme()) => {
+    const pygmentsDark = document.getElementById("pyg-dark")
+    const pygmentsLight = document.getElementById("pyg-light")
+    pygmentsDark.disabled = colourScheme === "light"
+    pygmentsLight.disabled = colourScheme === "dark"
+    pygmentsDark.media = colourScheme === "auto" ? "(prefers-color-scheme: dark)" : ""
+    pygmentsLight.media = colourScheme === "auto" ? "(prefers-color-scheme: light)" : ""
+}
+
+// Update Pygments state (the page theme is initialised inline, see page.html)
+document.addEventListener("DOMContentLoaded", () => setColourScheme())

pep_sphinx_extensions/pep_theme/static/colour_scheme.svg

@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" stroke-width="2" stroke="#777" fill="none" stroke-linecap="round" stroke-linejoin="round">
-<circle cx="12" cy="12" r="9"/>
-<path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"/>
-</svg>

pep_sphinx_extensions/pep_theme/static/dark.css

@@ -1,22 +0,0 @@
-@charset "UTF-8";
-/*
- * This stylesheet is separate from `style.css` to allow toggling dark mode with
- * a button, with no duplication of information
- */
-
-/* Set master 'dark-mode' colours */
-:root {
-    --colour-background: #011;
-    --colour-background-accent: #333;
-    --colour-text: #ccc;
-    --colour-links: #8bf;
-    --colour-scrollbar: #333;
-    --colour-rule-strong: #777;
-    --colour-rule-light: #222;
-    --colour-inline-code: #333;
-    --colour-warning: #900;
-}
-
-img.invert-in-dark-mode {
-    filter: invert(1);
-}

pep_sphinx_extensions/pep_theme/static/style.css

@@ -1,17 +1,49 @@
 @charset "UTF-8";
 /* Styles for PEPs */
 
-/* Set master 'light-mode' colours (default) */
+/*
+ * `initial` works like undefined variables, so `var(intial, x)` will resolve to `x`.
+ * A space means an empty value, so `var( , x) y` will resolve to `y`.
+ */
+@media (prefers-color-scheme: dark) {
+   :root {
+    --light: ;
+    --dark: initial;
+  }
+}
+
+@media (prefers-color-scheme: light) {
+   :root {
+    --dark: ;
+    --light: initial;
+  }
+}
+
+:root[data-colour_scheme="dark"] {
+  --light: ;
+  --dark: initial;
+}
+
+:root[data-colour_scheme="light"] {
+  --dark: ;
+  --light: initial;
+}
+
+/* Set master colours */
 :root {
-    --colour-background: white;
-    --colour-background-accent: #eee;
-    --colour-text: #333;
-    --colour-links: #0072aa;
-    --colour-scrollbar: #ccc;
-    --colour-rule-strong: #888;
-    --colour-rule-light: #ddd;
-    --colour-inline-code: #f8f8f8;
-    --colour-warning: #fee;
+    --colour-background: var(--light, white) var(--dark, #011);
+    --colour-background-accent: var(--light, #eee) var(--dark, #333);
+    --colour-text: var(--light, #333) var(--dark, #ccc);
+    --colour-links: var(--light, #0072aa) var(--dark, #8bf);
+    --colour-scrollbar: var(--light, #ccc) var(--dark, #333);
+    --colour-rule-strong: var(--light, #888) var(--dark, #777);
+    --colour-rule-light: var(--light, #ddd) var(--dark, #222);
+    --colour-inline-code: var(--light, #f8f8f8) var(--dark, #333);
+    --colour-warning: var(--light, #fee) var(--dark, #900);
+}
+
+img.invert-in-dark-mode {
+    filter: var(--dark, invert(1));
 }
 
 /* Set master rules */
@@ -234,15 +266,25 @@ ul.breadcrumbs a {
 }
 
 /* Dark mode toggle rules */
-section#pep-page-section > header > button {
-    background: transparent url(colour_scheme.svg) 0/contain;
+#colour-scheme-cycler {
+    background: transparent;
     border: none;
+    padding: 0;
     cursor: pointer;
     width: 1.2rem;
     height: 1.2rem;
     float: right;
     translate: 0 50%;
 }
+#colour-scheme-cycler svg {
+    color: var(--colour-rule-strong);
+    height: 1.2rem;
+    width: 1.2rem;
+    display: none;
+}
+:root[data-colour_scheme="auto"] #colour-scheme-cycler svg.colour-scheme-icon-when-auto {display: initial}
+:root[data-colour_scheme="dark"] #colour-scheme-cycler svg.colour-scheme-icon-when-dark {display: initial}
+:root[data-colour_scheme="light"] #colour-scheme-cycler svg.colour-scheme-icon-when-light {display: initial}
 
 /* Admonitions rules */
 div.note,

pep_sphinx_extensions/pep_theme/templates/page.html

@@ -10,14 +10,18 @@
     <link rel="canonical" href="{{ pageurl|escape }}" />
     <link rel="stylesheet" href="{{ pathto('_static/style.css', resource=True) }}" type="text/css" />
     <link rel="stylesheet" href="{{ pathto('_static/mq.css', resource=True) }}" type="text/css" />
-    <link rel="stylesheet" href="{{ pathto('_static/dark.css', resource=True) }}" type="text/css" media="(prefers-color-scheme: dark)" id="css-dark"/>
-    <link rel="stylesheet" href="{{ pathto('_static/pygments.css', resource=True) }}" type="text/css" media="(prefers-color-scheme: light)" id="pyg" />
+    <link rel="stylesheet" href="{{ pathto('_static/pygments.css', resource=True) }}" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light" />
     <link rel="stylesheet" href="{{ pathto('_static/pygments_dark.css', resource=True) }}" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark" />
     <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://www.python.org/dev/peps/peps.rss">
     <link href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">
     <meta name="description" content="Python Enhancement Proposals (PEPs)"/>
 </head>
 <body>
+    {% include "partials/icons.html" %}
+    <script>
+{# set colour scheme from local storage synchronously to avoid a flash of unstyled content #}
+        document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto"
+    </script>
     <section id="pep-page-section">
         <header>
             <h1>Python Enhancement Proposals</h1>
@@ -26,7 +30,11 @@
                 <li><a href="{{ pathto("pep-0000") }}">PEP Index</a> &raquo; </li>
                 <li>{{ title.split("–")[0].strip() }}</li>
             </ul>
-            <button aria-label="Toggle dark mode" onClick="toggleColourScheme()"></button>
+            <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())">
+                <svg class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
+                <svg class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg>
+                <svg class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg>
+            </button>
         </header>
         <article>
             {{ body }}

pep_sphinx_extensions/pep_theme/templates/partials/icons.html

@@ -0,0 +1,34 @@
+{# Adapted from Just the Docs → Furo #}
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+  <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all">
+    <title>Following system colour scheme</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
+         stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <circle cx="12" cy="12" r="9"></circle>
+      <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path>
+    </svg>
+  </symbol>
+  <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all">
+    <title>Selected dark colour scheme</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
+         stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
+      <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
+    </svg>
+  </symbol>
+  <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all">
+    <title>Selected light colour scheme</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
+         stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <circle cx="12" cy="12" r="5"></circle>
+      <line x1="12" y1="1" x2="12" y2="3"></line>
+      <line x1="12" y1="21" x2="12" y2="23"></line>
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+      <line x1="1" y1="12" x2="3" y2="12"></line>
+      <line x1="21" y1="12" x2="23" y2="12"></line>
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+    </svg>
+  </symbol>
+</svg>