refactor(theme-classic): replace color mode toggle with button; remove switchConfig

packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.ts

@@ -509,34 +509,24 @@ describe('themeConfig', () => {
     const withDefaultValues = (colorMode) =>
       _.merge({}, DEFAULT_CONFIG.colorMode, colorMode);
 
-    test('minimal config', () => {
+    test('switch config', () => {
       const colorMode = {
         switchConfig: {
           darkIcon: '🌙',
         },
       };
-      expect(testValidateThemeConfig({colorMode})).toEqual({
-        ...DEFAULT_CONFIG,
-        colorMode: withDefaultValues(colorMode),
-      });
+      expect(() =>
+        testValidateThemeConfig({colorMode}),
+      ).toThrowErrorMatchingInlineSnapshot(
+        `"colorMode.switchConfig is deprecated. If you want to customize the icons for light and dark mode, swizzle IconLightMode, IconDarkMode, or ColorModeToggle instead."`,
+      );
     });
 
     test('max config', () => {
       const colorMode = {
         defaultMode: 'dark',
         disableSwitch: false,
         respectPrefersColorScheme: true,
-        switchConfig: {
-          darkIcon: '🌙',
-          darkIconStyle: {
-            marginTop: '1px',
-            marginLeft: '2px',
-          },
-          lightIcon: '☀️',
-          lightIconStyle: {
-            marginLeft: '1px',
-          },
-        },
       };
       expect(testValidateThemeConfig({colorMode})).toEqual({
         ...DEFAULT_CONFIG,
@@ -562,16 +552,6 @@ describe('themeConfig', () => {
         },
       });
     });
-
-    test('empty switch config', () => {
-      const colorMode = {
-        switchConfig: {},
-      };
-      expect(testValidateThemeConfig({colorMode})).toEqual({
-        ...DEFAULT_CONFIG,
-        colorMode: withDefaultValues(colorMode),
-      });
-    });
   });
 });
 

packages/docusaurus-theme-classic/src/getSwizzleConfig.ts

@@ -7,94 +7,116 @@
 
 import type {SwizzleConfig} from '@docusaurus/types';
 
+/* eslint sort-keys: "error" */
+
 export default function getSwizzleConfig(): SwizzleConfig {
   return {
     components: {
       CodeBlock: {
         actions: {
-          wrap: 'safe',
           eject: 'safe',
+          wrap: 'safe',
         },
         description:
           'The component used to render multi-line code blocks, generally used in Markdown files.',
       },
-      DocSidebar: {
+      ColorModeToggle: {
         actions: {
+          eject: 'safe',
           wrap: 'safe',
+        },
+        description:
+          'The color mode toggle to switch between light and dark mode.',
+      },
+      DocSidebar: {
+        actions: {
           eject: 'unsafe', // too much technical code in sidebar, not very safe atm
+          wrap: 'safe',
         },
         description: 'The sidebar component on docs pages',
       },
       Footer: {
         actions: {
-          wrap: 'safe',
           eject: 'unsafe', // TODO split footer into smaller parts
+          wrap: 'safe',
         },
         description: "The footer component of you site's layout",
       },
-      NotFound: {
+      IconArrow: {
         actions: {
-          wrap: 'safe',
           eject: 'safe',
-        },
-        description:
-          'The global 404 page of your site, meant to be ejected and customized',
-      },
-      SearchBar: {
-        actions: {
           wrap: 'safe',
-          eject: 'safe',
         },
-        // TODO how to describe this one properly?
-        // By default it's an empty placeholder for the user to fill
-        description:
-          'The search bar component of your site, appearing in the navbar.',
+        description: 'The arrow icon component',
       },
-      IconArrow: {
+      IconDarkMode: {
         actions: {
-          wrap: 'safe',
           eject: 'safe',
+          wrap: 'safe',
         },
-        description: 'The arrow icon component',
+        description: 'The dark mode icon component.',
       },
       IconEdit: {
         actions: {
-          wrap: 'safe',
           eject: 'safe',
+          wrap: 'safe',
         },
         description: 'The edit icon component',
       },
-      IconMenu: {
+      IconLightMode: {
         actions: {
-          wrap: 'safe',
           eject: 'safe',
+          wrap: 'safe',
         },
-        description: 'The menu icon component',
+        description: 'The light mode icon component.',
       },
-
-      'prism-include-languages': {
+      IconMenu: {
         actions: {
-          wrap: 'forbidden', // not a component!
           eject: 'safe',
+          wrap: 'safe',
         },
-        description:
-          'The Prism languages to include for code block syntax highlighting. Meant to be ejected.',
+        description: 'The menu icon component',
       },
       MDXComponents: {
         actions: {
-          wrap: 'forbidden', /// TODO allow wrapping objects???
           eject: 'safe',
+          wrap: 'forbidden', /// TODO allow wrapping objects???
         },
         description:
           'The MDX components to use for rendering MDX files. Meant to be ejected.',
       },
-
       // TODO should probably not even appear here
       'NavbarItem/utils': {
         actions: {
-          wrap: 'forbidden',
           eject: 'forbidden',
+          wrap: 'forbidden',
+        },
+      },
+      NotFound: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The global 404 page of your site, meant to be ejected and customized',
+      },
+      SearchBar: {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
         },
+        // TODO how to describe this one properly?
+        // By default it's an empty placeholder for the user to fill
+        description:
+          'The search bar component of your site, appearing in the navbar.',
+      },
+      'prism-include-languages': {
+        actions: {
+          eject: 'safe',
+          wrap: 'forbidden', // not a component!
+        },
+        description:
+          'The Prism languages to include for code block syntax highlighting. Meant to be ejected.',
       },
     },
   };

packages/docusaurus-theme-classic/src/theme-classic.d.ts

@@ -632,7 +632,7 @@ declare module '@theme/TOCCollapsible' {
   export default function TOCCollapsible(props: Props): JSX.Element;
 }
 
-declare module '@theme/Toggle' {
+declare module '@theme/ColorModeToggle' {
   import type {SyntheticEvent} from 'react';
 
   export interface Props {
@@ -663,6 +663,14 @@ declare module '@theme/IconArrow' {
   export default function IconArrow(props: Props): JSX.Element;
 }
 
+declare module '@theme/IconDarkMode' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'svg'> {}
+
+  export default function IconDarkMode(props: Props): JSX.Element;
+}
+
 declare module '@theme/IconEdit' {
   import type {ComponentProps} from 'react';
 
@@ -671,6 +679,14 @@ declare module '@theme/IconEdit' {
   export default function IconEdit(props: Props): JSX.Element;
 }
 
+declare module '@theme/IconLightMode' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'svg'> {}
+
+  export default function IconLightMode(props: Props): JSX.Element;
+}
+
 declare module '@theme/IconMenu' {
   import type {ComponentProps} from 'react';
 

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

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React, {useState, useRef, useEffect} from 'react';
+import type {Props} from '@theme/ColorModeToggle';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {translate} from '@docusaurus/Translate';
+import IconLightMode from '@theme/IconLightMode';
+import IconDarkMode from '@theme/IconDarkMode';
+
+import clsx from 'clsx';
+import styles from './styles.module.css';
+
+function ColorModeToggle({
+  className,
+  checked: defaultChecked,
+  onChange,
+}: Props): JSX.Element {
+  const isBrowser = useIsBrowser();
+  const [checked, setChecked] = useState(defaultChecked);
+  const [focused, setFocused] = useState(false);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    setChecked(defaultChecked);
+  }, [defaultChecked]);
+
+  return (
+    <div
+      className={clsx(styles.toggle, className, {
+        [styles.toggleChecked]: checked,
+        [styles.toggleFocused]: focused,
+        [styles.toggleDisabled]: !isBrowser,
+      })}>
+      {/* eslint-disable-next-line jsx-a11y/click-events-have-key-events */}
+      <div
+        className={styles.toggleButton}
+        role="button"
+        tabIndex={-1}
+        onClick={() => inputRef.current?.click()}>
+        <IconLightMode
+          className={clsx(styles.toggleIcon, styles.lightToggleIcon)}
+        />
+        <IconDarkMode
+          className={clsx(styles.toggleIcon, styles.darkToggleIcon)}
+        />
+      </div>
+
+      <input
+        ref={inputRef}
+        checked={checked}
+        type="checkbox"
+        className={styles.toggleScreenReader}
+        aria-label={translate(
+          {
+            message: 'Switch between dark and light mode (currently {mode})',
+            id: 'theme.colorToggle.ariaLabel',
+            description: 'The ARIA label for the navbar color mode toggle',
+          },
+          {
+            mode: checked
+              ? translate({
+                  message: 'dark mode',
+                  id: 'theme.colorToggle.ariaLabel.mode.dark',
+                  description: 'The name for the dark color mode',
+                })
+              : translate({
+                  message: 'light mode',
+                  id: 'theme.colorToggle.ariaLabel.mode.light',
+                  description: 'The name for the light color mode',
+                }),
+          },
+        )}
+        onChange={onChange}
+        onClick={() => setChecked(!checked)}
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') {
+            inputRef.current?.click();
+          }
+        }}
+      />
+    </div>
+  );
+}
+
+export default React.memo(ColorModeToggle);

packages/docusaurus-theme-classic/src/theme/ColorModeToggle/styles.module.css

@@ -0,0 +1,51 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.toggle {
+  position: relative;
+  width: 32px;
+  height: 32px;
+}
+
+.toggleScreenReader {
+  border: 0;
+  clip: rect(0 0 0 0);
+  height: 1px;
+  margin: -1px;
+  overflow: hidden;
+  position: absolute;
+  width: 1px;
+}
+
+.toggleDisabled {
+  cursor: not-allowed;
+}
+
+.toggleButton {
+  cursor: pointer;
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
+  align-items: center;
+  display: flex;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  border-radius: 50%;
+}
+
+.toggleButton:hover {
+  background-color: #00000010;
+}
+
+[data-theme='dark'] .toggleButton:hover {
+  background-color: #ffffff20;
+}
+
+[data-theme='light'] .darkToggleIcon,
+[data-theme='dark'] .lightToggleIcon {
+  display: none;
+}