fix(v2): refactor color mode system (#3012)

* refactor color mode system to enable all possibilities

* fix destructuring bug

* colorMode validation + deprecation + minor name changes + doc

* rename method noFlashColorMode

* fix doc wording

* docs wording

* docs wording

* re-enable theme config merging/normalization + colorMode fixes

* document theme normalization

* code review changes

.prettierignore

@@ -14,4 +14,5 @@ packages/docusaurus-plugin-content-pages/lib/
 packages/docusaurus-plugin-debug/lib/
 packages/docusaurus-plugin-sitemap/lib/
 packages/docusaurus-plugin-ideal-image/lib/
+packages/docusaurus-theme-classic/lib/
 __fixtures__

packages/docusaurus-theme-classic/src/index.js

@@ -20,41 +20,49 @@ const ContextReplacementPlugin = requireFromDocusaurusCore(
 // Need to be inlined to prevent dark mode FOUC
 // Make sure that the 'storageKey' is the same as the one in `/theme/hooks/useTheme.js`
 const storageKey = 'theme';
-const noFlash = (defaultDarkMode) => `(function() {
-  var defaultDarkMode = ${defaultDarkMode};
+const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
+  return `(function() {
+  var defaultMode = '${defaultMode}';
+  var respectPrefersColorScheme = ${respectPrefersColorScheme};
 
   function setDataThemeAttribute(theme) {
     document.documentElement.setAttribute('data-theme', theme);
   }
 
-  function getPreferredTheme() {
+  function getStoredTheme() {
     var theme = null;
     try {
       theme = localStorage.getItem('${storageKey}');
     } catch (err) {}
-
     return theme;
   }
 
-  var darkQuery = window.matchMedia('(prefers-color-scheme: dark)');
-
-  var preferredTheme = getPreferredTheme();
-  if (preferredTheme !== null) {
-    setDataThemeAttribute(preferredTheme);
-  } else if (darkQuery.matches || defaultDarkMode) {
+  var storedTheme = getStoredTheme();
+  if (storedTheme !== null) {
+    setDataThemeAttribute(storedTheme);
+  } else {
+    if (
+      respectPrefersColorScheme &&
+      window.matchMedia('(prefers-color-scheme: dark)').matches
+    ) {
       setDataThemeAttribute('dark');
+    } else if (
+      respectPrefersColorScheme &&
+      window.matchMedia('(prefers-color-scheme: light)').matches
+    ) {
+      setDataThemeAttribute('light');
+    } else {
+      setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
+    }
   }
 })();`;
+};
 
 module.exports = function (context, options) {
   const {
     siteConfig: {themeConfig},
   } = context;
-  const {
-    disableDarkMode = false,
-    defaultDarkMode = false,
-    prism: {additionalLanguages = []} = {},
-  } = themeConfig || {};
+  const {colorMode, prism: {additionalLanguages = []} = {}} = themeConfig || {};
   const {customCss} = options || {};
 
   return {
@@ -97,9 +105,6 @@ module.exports = function (context, options) {
     },
 
     injectHtmlTags() {
-      if (disableDarkMode) {
-        return {};
-      }
       return {
         preBodyTags: [
           {
@@ -107,7 +112,7 @@ module.exports = function (context, options) {
             attributes: {
               type: 'text/javascript',
             },
-            innerHTML: noFlash(defaultDarkMode),
+            innerHTML: noFlashColorMode(colorMode),
           },
         ],
       };
@@ -130,8 +135,26 @@ const NavbarLinkSchema = Joi.object({
   .xor('href', 'to')
   .id('navbarLinkSchema');
 
+const ColorModeSchema = Joi.object({
+  defaultMode: Joi.string().equal('dark', 'light').default('light'),
+  disableSwitch: Joi.bool().default(false),
+  respectPrefersColorScheme: Joi.bool().default(false),
+}).default({
+  defaultMode: 'light',
+  disableSwitch: false,
+  respectPrefersColorScheme: false,
+});
+
 const ThemeConfigSchema = Joi.object({
-  disableDarkMode: Joi.bool().default(false),
+  disableDarkMode: Joi.any().forbidden(false).messages({
+    'any.unknown':
+      'disableDarkMode theme config is deprecated. Please use the new colorMode attribute. You likely want: config.themeConfig.colorMode.disableSwitch = true',
+  }),
+  defaultDarkMode: Joi.any().forbidden(false).messages({
+    'any.unknown':
+      'defaultDarkMode theme config is deprecated. Please use the new colorMode attribute. You likely want: config.themeConfig.colorMode.defaultMode = "dark"',
+  }),
+  colorMode: ColorModeSchema,
   image: Joi.string(),
   announcementBar: Joi.object({
     id: Joi.string(),

packages/docusaurus-theme-classic/src/theme/Navbar/index.tsx

@@ -185,7 +185,7 @@ function Navbar(): JSX.Element {
     siteConfig: {
       themeConfig: {
         navbar: {title = '', links = [], hideOnScroll = false} = {},
-        disableDarkMode = false,
+        colorMode: {disableSwitch: disableColorModeSwitch = false} = {},
       },
     },
     isClient,
@@ -283,7 +283,7 @@ function Navbar(): JSX.Element {
           {rightLinks.map((linkItem, i) => (
             <NavItem {...linkItem} key={i} />
           ))}
-          {!disableDarkMode && (
+          {!disableColorModeSwitch && (
             <Toggle
               className={styles.displayOnlyInLargeViewport}
               aria-label="Dark mode toggle"
@@ -321,7 +321,7 @@ function Navbar(): JSX.Element {
               <strong className="navbar__title">{title}</strong>
             )}
           </Link>
-          {!disableDarkMode && sidebarShown && (
+          {!disableColorModeSwitch && sidebarShown && (
             <Toggle
               aria-label="Dark mode toggle in sidebar"
               checked={isDarkTheme}

packages/docusaurus-theme-classic/src/theme/hooks/useTheme.ts

@@ -8,58 +8,67 @@
 import {useState, useCallback, useEffect} from 'react';
 
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 
 const themes = {
-  light: '',
+  light: 'light',
   dark: 'dark',
 };
 
+// Ensure to always return a valid theme even if input is invalid
+const coerceToTheme = (theme) => {
+  return theme === themes.dark ? themes.dark : themes.light;
+};
+
+const getInitialTheme = () => {
+  if (!ExecutionEnvironment.canUseDOM) {
+    return themes.light; // SSR: we don't care
+  }
+  return coerceToTheme(document.documentElement.getAttribute('data-theme'));
+};
+
+const storeTheme = (newTheme) => {
+  try {
+    localStorage.setItem('theme', coerceToTheme(newTheme));
+  } catch (err) {
+    console.error(err);
+  }
+};
+
 const useTheme = (): {
   isDarkTheme: boolean;
   setLightTheme: () => void;
   setDarkTheme: () => void;
 } => {
   const {
-    siteConfig: {themeConfig: {disableDarkMode = false} = {}} = {},
+    siteConfig: {
+      themeConfig: {colorMode: {disableSwitch = false} = {}} = {},
+    } = {},
   } = useDocusaurusContext();
-  const [theme, setTheme] = useState(
-    typeof document !== 'undefined'
-      ? document.documentElement.getAttribute('data-theme')
-      : themes.light,
-  );
-  const setThemeSyncWithLocalStorage = useCallback(
-    (newTheme) => {
-      try {
-        localStorage.setItem('theme', newTheme);
-      } catch (err) {
-        console.error(err);
-      }
-    },
-    [setTheme],
-  );
+  const [theme, setTheme] = useState(getInitialTheme);
+
   const setLightTheme = useCallback(() => {
     setTheme(themes.light);
-    setThemeSyncWithLocalStorage(themes.light);
+    storeTheme(themes.light);
   }, []);
   const setDarkTheme = useCallback(() => {
     setTheme(themes.dark);
-    setThemeSyncWithLocalStorage(themes.dark);
+    storeTheme(themes.dark);
   }, []);
 
   useEffect(() => {
-    // @ts-expect-error: safe to set null as attribute
-    document.documentElement.setAttribute('data-theme', theme);
+    document.documentElement.setAttribute('data-theme', coerceToTheme(theme));
   }, [theme]);
 
   useEffect(() => {
-    if (disableDarkMode) {
+    if (disableSwitch) {
       return;
     }
 
     try {
       const localStorageTheme = localStorage.getItem('theme');
       if (localStorageTheme !== null) {
-        setTheme(localStorageTheme);
+        setTheme(coerceToTheme(localStorageTheme));
       }
     } catch (err) {
       console.error(err);
@@ -67,7 +76,7 @@ const useTheme = (): {
   }, [setTheme]);
 
   useEffect(() => {
-    if (disableDarkMode) {
+    if (disableSwitch) {
       return;
     }
 

packages/docusaurus/src/server/plugins/init.ts

@@ -83,11 +83,11 @@ export default function initPlugins({
         pluginModule.default?.validateOptions ?? pluginModule.validateOptions;
 
       if (validateOptions) {
-        const options = validateOptions({
+        const normalizedOptions = validateOptions({
           validate,
           options: pluginOptions,
         });
-        pluginOptions = options;
+        pluginOptions = normalizedOptions;
       }
 
       // support both commonjs and ES modules
@@ -96,10 +96,15 @@ export default function initPlugins({
         pluginModule.validateThemeConfig;
 
       if (validateThemeConfig) {
-        validateThemeConfig({
+        const normalizedThemeConfig = validateThemeConfig({
           validate: validateAndStrip,
           themeConfig: context.siteConfig.themeConfig,
         });
+
+        context.siteConfig.themeConfig = {
+          ...context.siteConfig.themeConfig,
+          ...normalizedThemeConfig,
+        };
       }
       return plugin(context, pluginOptions);
     })

website/docs/lifecycle-apis.md

@@ -63,11 +63,11 @@ export function validateOptions({options, validate}) {
 
 ## `validateThemeConfig({themeConfig,validate})`
 
-Validate `themeConfig` for the plugins and theme. This method is called before the plugin is initialized.
+Return validated and normalized configuration for the theme.
 
 ### `themeConfig`
 
-`validateThemeConfig` is called with `themeConfig` provided in `docusaurus.config.js` for validation.
+`validateThemeConfig` is called with `themeConfig` provided in `docusaurus.config.js` for validation and normalization.
 
 ### `validate`
 
@@ -75,7 +75,7 @@ Validate `themeConfig` for the plugins and theme. This method is called before t
 
 :::tip
 
-[Joi](https://www.npmjs.com/package/@hapi/joi) is recommended for validation and normalization of options.
+[Joi](https://www.npmjs.com/package/@hapi/joi) is recommended for validation and normalization of theme config.
 
 :::
 
@@ -90,7 +90,8 @@ module.exports = function (context, options) {
 };
 
 module.exports.validateThemeConfig = ({themeConfig, validate}) => {
-  validate(myValidationSchema, options);
+  const validatedThemeConfig = validate(myValidationSchema, options);
+  return validatedThemeConfig;
 };
 ```
 
@@ -105,7 +106,8 @@ export default function (context, options) {
 }
 
 export function validateThemeConfig({themeConfig, validate}) {
-  validate(myValidationSchema, options);
+  const validatedThemeConfig = validate(myValidationSchema, options);
+  return validatedThemeConfig;
 }
 ```
 

website/docs/theme-classic.md

@@ -11,31 +11,42 @@ This section is a work in progress.
 
 ## Common
 
-### Dark mode
+### Color mode - dark mode
 
-To remove the ability to switch on dark mode, there is an option `themeConfig.disableDarkMode`, which is implicitly set to `false`.
+The classic theme provides by default light and dark mode support, with a navbar switch for the user.
 
-```js {4} title="docusaurus.config.js"
+It is possible to customize the color mode support with the following configuration:
+
+```js {6-15} title="docusaurus.config.js"
 module.exports = {
   // ...
   themeConfig: {
-    disableDarkMode: false,
+    // ...
+    colorMode: {
+      // "light" | "dark"
+      defaultMode: 'light',
+
+      // Hides the switch in the navbar
+      // Useful if you want to support a single color mode
+      disableSwitch: false,
+
+      // Should we use the prefers-color-scheme media-query,
+      // using user system preferences, instead of the hardcoded defaultMode
+      respectPrefersColorScheme: false,
+    },
     // ...
   },
+  // ...
 };
 ```
 
-With the enabled `defaultDarkMode` option you could set dark mode by default. However, in this case, the user's preference will not be taken into account until they manually sets the desired mode via toggle in the navbar.
+:::caution
 
-```js {4} title="docusaurus.config.js"
-module.exports = {
-  // ...
-  themeConfig: {
-    defaultDarkMode: true,
-    // ...
-  },
-};
-```
+With `respectPrefersColorScheme: true`, the `defaultMode` is overridden by user system preferences.
+
+If you only want to support one color mode, you likely want to ignore user system preferences.
+
+:::
 
 ### Meta image
 

website/docusaurus.config.js

@@ -81,6 +81,11 @@ module.exports = {
     ],
   ],
   themeConfig: {
+    colorMode: {
+      defaultMode: 'light',
+      disableSwitch: false,
+      respectPrefersColorScheme: true,
+    },
     announcementBar: {
       id: 'supportus',
       content: