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

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,32 +11,43 @@ 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.
-
-```js {4} title="docusaurus.config.js"
-module.exports = {
   // ...
-  themeConfig: {
-    defaultDarkMode: true,
-    // ...
-  },
 };
 ```
 
+:::caution
+
+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
 
 You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`.