feat(theme): allow reverting to auto theme mode

[nasso]

Pre-flight checklist

• [x] I have read the Contributing Guidelines on pull requests.
• [ ] If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• [x] If this is a new API or substantial change: the PR has an accompanying issue (closes #8074) and the maintainers have approved on my working plan.

Motivation

See #8074.

When the user changes the theme manually by clicking on the toggle, the user's preference gets persisted in localStorage, and there's no way to go back to the system/OS/browser theme (which I just call "auto"; browser is free to report anything it wants, not necessarily what it or the OS is using). I added a third state to the existing toggle, that allows the user to set the theme to "automatic" mode, which will honour prefers-color-scheme. The preference of the user is still persisted to localStorage, except now we sometimes store theme=auto. I created a rudimentary icon in Figma, inspired by MDN's icon but in the style of the rest of the icons in Docusaurus' classic theme (i.e. stroke width, margins).

As described in https://github.com/facebook/docusaurus/issues/8074#issuecomment-1342662517, a colorModeChoice was introduced to support the third value: auto. colorMode is now computed from colorModeChoice, the source of truth. I also followed the same logic for the state machine cycling logic.

On the DOM side of things (what actually changes the theme), the data-theme attribute still contains either dark or light (I thought about allowing it to be auto and using CSS media queries but that's too much work right now, so probably out of scope). To support the third state in the theme toggle button, I added a data-theme-choice attribute, that may also be auto. The logic otherwise stays the same.

Finally, the current configuration options include respectPrefersColorScheme, which is used to determine whether light or dark should be used when the user has not manually changed the theme. I deprecated respectPrefersColorScheme in favour of a third possible value for defaultMode: auto. This makes the logic much easier to follow: light will always be light, dark will always be dark, and auto will always use whatever is the preferred colour scheme.

Test Plan

I think the only way to test it would be with E2E tests? I did not add any because I couldn't find any test for the previous behaviour (i.e. clicking the toggle changes the data-theme attribute).

prefers-color-scheme: dark

prefers-color-scheme: light

Test links

Deploy preview: https://deploy-preview-8474--docusaurus-2.netlify.app/

Related issues/PRs

Fixes #8074.

[nasso]

I'm getting errors like:

[ERROR] Docusaurus server-side rendering could not render static page with path /.
[INFO] It looks like you are using code that should run on the client-side only.
To get around it, try using `<BrowserOnly>` (https://docusaurus.io/docs/docusaurus-core/#browseronly) or `ExecutionEnvironment` (https://docusaurus.io/docs/docusaurus-core/#executionenvironment).
It might also require to wrap your client code in `useEffect` hook and/or import a third-party library dynamically (if any).

...

ReferenceError: window is not defined
ReferenceError: window is not defined
ReferenceError: window is not defined
ReferenceError: window is not defined
...
ReferenceError: window is not defined
ReferenceError: window is not defined
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
    at /workspaces/docusaurus/packages/docusaurus/lib/webpack/utils.js:180:24
    at /workspaces/docusaurus/node_modules/webpack/lib/MultiCompiler.js:554:14
    at processQueueWorker (/workspaces/docusaurus/node_modules/webpack/lib/MultiCompiler.js:491:6)
    at process.processTicksAndRejections (node:internal/process/task_queues:77:11)

I don't really understand why nor how I can debug this. Any hint?

[netlify[bot]]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	51176f17cf7c2bf8e940c80ea24b46e13e6d156a
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/63ed84fd34c1830008306f7f
😎 Deploy Preview	https://deploy-preview-8474--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions[bot]]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 87	🟢 97	🟢 100	🟢 100	🟢 90	Report
/docs/installation	🟠 82	🟢 100	🟢 100	🟢 100	🟢 90	Report

[nasso]

woops didnt know github would remove the other review requests 🤔