@docusaurus/theme-classic 2.0.0-beta.138b4c997 → 2.0.0-beta.14

package/src/theme/ThemedImage/index.tsx

@@ -8,14 +8,14 @@
 import React from 'react';
 import clsx from 'clsx';
 
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 import useThemeContext from '@theme/hooks/useThemeContext';
 import type {Props} from '@theme/ThemedImage';
 
 import styles from './styles.module.css';
 
-const ThemedImage = (props: Props): JSX.Element => {
-  const {isClient} = useDocusaurusContext();
+function ThemedImage(props: Props): JSX.Element {
+  const isBrowser = useIsBrowser();
   const {isDarkTheme} = useThemeContext();
   const {sources, className, alt = '', ...propsRest} = props;
 
@@ -23,7 +23,7 @@ const ThemedImage = (props: Props): JSX.Element => {
 
   const clientThemes: SourceName[] = isDarkTheme ? ['dark'] : ['light'];
 
-  const renderedSourceNames: SourceName[] = isClient
+  const renderedSourceNames: SourceName[] = isBrowser
     ? clientThemes
     : // We need to render both images on the server to avoid flash
       // See https://github.com/facebook/docusaurus/pull/3730
@@ -46,6 +46,6 @@ const ThemedImage = (props: Props): JSX.Element => {
       ))}
     </>
   );
-};
+}
 
 export default ThemedImage;

package/src/theme/Toggle/index.tsx

@@ -5,95 +5,88 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useState, useRef, memo, CSSProperties} from 'react';
+import React, {useState, useRef, memo} from 'react';
 import type {Props} from '@theme/Toggle';
-import {useThemeConfig} from '@docusaurus/theme-common';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useThemeConfig, ColorModeConfig} from '@docusaurus/theme-common';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 
 import clsx from 'clsx';
-import './styles.css';
 import styles from './styles.module.css';
 
-interface IconProps {
-  icon: string;
-  style: CSSProperties;
-}
-
-const Dark = ({icon, style}: IconProps): JSX.Element => (
-  <span className={clsx(styles.toggle, styles.dark)} style={style}>
-    {icon}
-  </span>
-);
-const Light = ({icon, style}: IconProps): JSX.Element => (
-  <span className={clsx(styles.toggle, styles.light)} style={style}>
-    {icon}
-  </span>
-);
-
 // Based on react-toggle (https://github.com/aaronshaf/react-toggle/).
-const Toggle = memo(
+const ToggleComponent = memo(
   ({
     className,
-    icons,
+    switchConfig,
     checked: defaultChecked,
     disabled,
     onChange,
   }: Props & {
-    icons: {checked: JSX.Element; unchecked: JSX.Element};
+    switchConfig: ColorModeConfig['switchConfig'];
     disabled: boolean;
   }): JSX.Element => {
+    const {darkIcon, darkIconStyle, lightIcon, lightIconStyle} = switchConfig;
     const [checked, setChecked] = useState(defaultChecked);
     const [focused, setFocused] = useState(false);
     const inputRef = useRef<HTMLInputElement>(null);
 
     return (
       <div
-        className={clsx('react-toggle', className, {
-          'react-toggle--checked': checked,
-          'react-toggle--focus': focused,
-          'react-toggle--disabled': disabled,
+        className={clsx(styles.toggle, className, {
+          [styles.toggleChecked]: checked,
+          [styles.toggleFocused]: focused,
+          [styles.toggleDisabled]: disabled,
         })}>
+        {/* eslint-disable-next-line jsx-a11y/click-events-have-key-events */}
         <div
-          className="react-toggle-track"
+          className={styles.toggleTrack}
           role="button"
           tabIndex={-1}
           onClick={() => inputRef.current?.click()}>
-          <div className="react-toggle-track-check">{icons.checked}</div>
-          <div className="react-toggle-track-x">{icons.unchecked}</div>
-          <div className="react-toggle-thumb" />
+          <div className={styles.toggleTrackCheck}>
+            <span className={styles.toggleIcon} style={darkIconStyle}>
+              {darkIcon}
+            </span>
+          </div>
+          <div className={styles.toggleTrackX}>
+            <span className={styles.toggleIcon} style={lightIconStyle}>
+              {lightIcon}
+            </span>
+          </div>
+          <div className={styles.toggleTrackThumb} />
         </div>
 
         <input
           ref={inputRef}
           checked={checked}
           type="checkbox"
-          className="react-toggle-screenreader-only"
+          className={styles.toggleScreenReader}
           aria-label="Switch between dark and light mode"
           onChange={onChange}
           onClick={() => setChecked(!checked)}
           onFocus={() => setFocused(true)}
           onBlur={() => setFocused(false)}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') {
+              inputRef.current?.click();
+            }
+          }}
         />
       </div>
     );
   },
 );
 
-export default function (props: Props): JSX.Element {
+export default function Toggle(props: Props): JSX.Element {
   const {
-    colorMode: {
-      switchConfig: {darkIcon, darkIconStyle, lightIcon, lightIconStyle},
-    },
+    colorMode: {switchConfig},
   } = useThemeConfig();
-  const {isClient} = useDocusaurusContext();
+  const isBrowser = useIsBrowser();
 
   return (
-    <Toggle
-      disabled={!isClient}
-      icons={{
-        checked: <Dark icon={darkIcon} style={darkIconStyle} />,
-        unchecked: <Light icon={lightIcon} style={lightIconStyle} />,
-      }}
+    <ToggleComponent
+      switchConfig={switchConfig}
+      disabled={!isBrowser}
       {...props}
     />
   );

package/src/theme/Toggle/styles.module.css

@@ -6,12 +6,100 @@
  */
 
 .toggle {
+  touch-action: pan-x;
+  position: relative;
+  cursor: pointer;
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
+}
+
+.toggleScreenReader {
+  border: 0;
+  clip: rect(0 0 0 0);
+  height: 1px;
+  margin: -1px;
+  overflow: hidden;
+  position: absolute;
+  width: 1px;
+}
+
+.toggleDisabled {
+  cursor: not-allowed;
+}
+
+.toggleTrack {
+  width: 50px;
+  height: 24px;
+  border-radius: 30px;
+  background-color: #4d4d4d;
+  transition: all 0.2s ease;
+}
+
+.toggleTrackCheck {
+  position: absolute;
+  width: 14px;
+  height: 10px;
+  top: 0px;
+  bottom: 0px;
+  margin: auto 0;
+  left: 8px;
+  opacity: 0;
+  transition: opacity 0.25s ease;
+}
+
+[data-theme='dark'] .toggle .toggleTrackCheck,
+.toggleChecked .toggleTrackCheck {
+  opacity: 1;
+  transition: opacity 0.25s ease;
+}
+
+.toggleTrackX {
+  position: absolute;
+  width: 10px;
+  height: 10px;
+  top: 0px;
+  bottom: 0px;
+  margin: auto 0;
+  right: 10px;
+  opacity: 1;
+  transition: opacity 0.25s ease;
+}
+
+[data-theme='dark'] .toggle .toggleTrackX,
+.toggleChecked .toggleTrackX {
+  opacity: 0;
+}
+
+.toggleTrackThumb {
+  position: absolute;
+  top: 1px;
+  left: 1px;
+  width: 22px;
+  height: 22px;
+  border: 1px solid #4d4d4d;
+  border-radius: 50%;
+  background-color: #fafafa;
+  transition: all 0.25s ease;
+}
+
+[data-theme='dark'] .toggle .toggleTrackThumb,
+.toggleChecked .toggleTrackThumb {
+  left: 27px;
+}
+
+.toggleFocused .toggleTrackThumb,
+.toggle:hover .toggleTrackThumb {
+  box-shadow: 0px 0px 2px 3px var(--ifm-color-primary);
+}
+
+.toggle:active:not(.toggleDisabled) .toggleTrackThumb {
+  box-shadow: 0px 0px 5px 5px var(--ifm-color-primary);
+}
+
+.toggleIcon {
   align-items: center;
   display: flex;
   height: 10px;
   justify-content: center;
   width: 10px;
 }
-.toggle::before {
-  position: absolute;
-}

package/src/theme/UserPreferencesProvider/index.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {useMemo} from 'react';
 
 import useTabGroupChoice from '@theme/hooks/useTabGroupChoice';
 import UserPreferencesContext from '@theme/UserPreferencesContext';
@@ -13,12 +13,15 @@ import type {Props} from '@theme/UserPreferencesProvider';
 
 function UserPreferencesProvider(props: Props): JSX.Element {
   const {tabGroupChoices, setTabGroupChoices} = useTabGroupChoice();
+  const contextValue = useMemo(
+    () => ({
+      tabGroupChoices,
+      setTabGroupChoices,
+    }),
+    [tabGroupChoices, setTabGroupChoices],
+  );
   return (
-    <UserPreferencesContext.Provider
-      value={{
-        tabGroupChoices,
-        setTabGroupChoices,
-      }}>
+    <UserPreferencesContext.Provider value={contextValue}>
       {props.children}
     </UserPreferencesContext.Provider>
   );

package/src/theme/hooks/useHideableNavbar.ts

@@ -5,76 +5,63 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useState, useCallback, useEffect, useRef} from 'react';
-import {useLocation} from '@docusaurus/router';
-import useScrollPosition from '@theme/hooks/useScrollPosition';
-import {useLocationChange} from '@docusaurus/theme-common';
+import {useState, useCallback, useRef} from 'react';
+import {useLocationChange, useScrollPosition} from '@docusaurus/theme-common';
 import type {useHideableNavbarReturns} from '@theme/hooks/useHideableNavbar';
 
 const useHideableNavbar = (hideOnScroll: boolean): useHideableNavbarReturns => {
-  const location = useLocation();
   const [isNavbarVisible, setIsNavbarVisible] = useState(hideOnScroll);
   const isFocusedAnchor = useRef(false);
-  const [navbarHeight, setNavbarHeight] = useState(0);
+  const navbarHeight = useRef(0);
   const navbarRef = useCallback((node: HTMLElement | null) => {
     if (node !== null) {
-      setNavbarHeight(node.getBoundingClientRect().height);
+      navbarHeight.current = node.getBoundingClientRect().height;
     }
   }, []);
 
-  useScrollPosition(
-    ({scrollY: scrollTop}, {scrollY: lastScrollTop}) => {
-      if (!hideOnScroll) {
-        return;
-      }
-
-      if (scrollTop < navbarHeight) {
-        setIsNavbarVisible(true);
-        return;
-      }
-
-      if (isFocusedAnchor.current) {
-        isFocusedAnchor.current = false;
-        setIsNavbarVisible(false);
-        return;
-      }
-
-      if (lastScrollTop && scrollTop === 0) {
-        setIsNavbarVisible(true);
-      }
+  useScrollPosition((currentPosition, lastPosition) => {
+    if (!hideOnScroll) {
+      return;
+    }
 
-      const documentHeight =
-        document.documentElement.scrollHeight - navbarHeight;
-      const windowHeight = window.innerHeight;
+    const scrollTop = currentPosition.scrollY;
 
-      if (lastScrollTop && scrollTop >= lastScrollTop) {
-        setIsNavbarVisible(false);
-      } else if (scrollTop + windowHeight < documentHeight) {
-        setIsNavbarVisible(true);
-      }
-    },
-    [navbarHeight, isFocusedAnchor],
-  );
+    // It needed for mostly to handle rubber band scrolling
+    if (scrollTop < navbarHeight.current) {
+      setIsNavbarVisible(true);
+      return;
+    }
 
-  useLocationChange((locationChangeEvent) => {
-    if (!hideOnScroll || locationChangeEvent.location.hash) {
+    if (isFocusedAnchor.current) {
+      isFocusedAnchor.current = false;
       return;
     }
 
-    setIsNavbarVisible(true);
+    const lastScrollTop = lastPosition?.scrollY;
+    const documentHeight =
+      document.documentElement.scrollHeight - navbarHeight.current;
+    const windowHeight = window.innerHeight;
+
+    if (lastScrollTop && scrollTop >= lastScrollTop) {
+      setIsNavbarVisible(false);
+    } else if (scrollTop + windowHeight < documentHeight) {
+      setIsNavbarVisible(true);
+    }
   });
 
-  useEffect(() => {
+  useLocationChange((locationChangeEvent) => {
     if (!hideOnScroll) {
       return;
     }
 
-    if (!location.hash) {
+    if (locationChangeEvent.location.hash) {
+      isFocusedAnchor.current = true;
+      setIsNavbarVisible(false);
       return;
     }
 
-    isFocusedAnchor.current = true;
-  }, [location.hash]);
+    setIsNavbarVisible(true);
+  });
 
   return {
     navbarRef,

package/src/theme/hooks/useTabGroupChoice.ts

@@ -21,11 +21,11 @@ const useTabGroupChoice = (): useTabGroupChoiceReturns => {
 
   useEffect(() => {
     try {
-      const localStorageChoices = {};
+      const localStorageChoices: Record<string, string> = {};
       listStorageKeys().forEach((storageKey) => {
         if (storageKey.startsWith(TAB_CHOICE_PREFIX)) {
           const groupId = storageKey.substring(TAB_CHOICE_PREFIX.length);
-          localStorageChoices[groupId] = createStorageSlot(storageKey).get();
+          localStorageChoices[groupId] = createStorageSlot(storageKey).get()!;
         }
       });
       setChoices(localStorageChoices);

package/src/theme/hooks/useTheme.ts

@@ -21,9 +21,8 @@ const themes = {
 type Themes = typeof themes[keyof typeof themes];
 
 // Ensure to always return a valid theme even if input is invalid
-const coerceToTheme = (theme?: string | null): Themes => {
-  return theme === themes.dark ? themes.dark : themes.light;
-};
+const coerceToTheme = (theme?: string | null): Themes =>
+  theme === themes.dark ? themes.dark : themes.light;
 
 const getInitialTheme = (defaultMode: Themes | undefined): Themes => {
   if (!ExecutionEnvironment.canUseDOM) {
@@ -68,7 +67,7 @@ const useTheme = (): useThemeReturns => {
     } catch (err) {
       console.error(err);
     }
-  }, [setTheme]);
+  }, [disableSwitch, setTheme]);
 
   useEffect(() => {
     if (disableSwitch && !respectPrefersColorScheme) {
@@ -80,7 +79,7 @@ const useTheme = (): useThemeReturns => {
       .addListener(({matches}) => {
         setTheme(matches ? themes.dark : themes.light);
       });
-  }, []);
+  }, [disableSwitch, respectPrefersColorScheme]);
 
   return {
     isDarkTheme: theme === themes.dark,

package/src/theme/hooks/useWindowSize.ts

@@ -10,42 +10,60 @@ import {useEffect, useState} from 'react';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import type {WindowSize} from '@theme/hooks/useWindowSize';
 
-const desktopThresholdWidth = 996;
-
 const windowSizes = {
   desktop: 'desktop',
   mobile: 'mobile',
+
+  // This "ssr" value is very important to handle hydration FOUC / layout shifts
+  // You have to handle server-rendering explicitly on the call-site
+  // On the server, you may need to render BOTH the mobile/desktop elements (and hide one of them with mediaquery)
+  // We don't return "undefined" on purpose, to make it more explicit
+  ssr: 'ssr',
 } as const;
 
-function useWindowSize(): WindowSize | undefined {
-  const isClient = ExecutionEnvironment.canUseDOM;
+const DesktopThresholdWidth = 996;
 
-  function getSize() {
-    if (!isClient) {
-      return undefined;
-    }
-    return window.innerWidth > desktopThresholdWidth
-      ? windowSizes.desktop
-      : windowSizes.mobile;
+function getWindowSize() {
+  if (!ExecutionEnvironment.canUseDOM) {
+    return windowSizes.ssr;
   }
+  return window.innerWidth > DesktopThresholdWidth
+    ? windowSizes.desktop
+    : windowSizes.mobile;
+}
 
-  const [windowSize, setWindowSize] = useState(getSize);
+// Simulate the SSR window size in dev, so that potential hydration FOUC/layout shift problems can be seen in dev too!
+const DevSimulateSSR = process.env.NODE_ENV === 'development' && true;
 
-  useEffect(() => {
-    if (!isClient) {
-      return undefined;
+// This hook returns an enum value on purpose!
+// We don't want it to return the actual width value, for resize perf reasons
+// We only want to re-render once a breakpoint is crossed
+function useWindowSize(): WindowSize {
+  const [windowSize, setWindowSize] = useState<WindowSize>(() => {
+    if (DevSimulateSSR) {
+      return 'ssr';
     }
+    return getWindowSize();
+  });
 
-    function handleResize() {
-      setWindowSize(getSize());
+  useEffect(() => {
+    function updateWindowSize() {
+      setWindowSize(getWindowSize());
     }
 
-    window.addEventListener('resize', handleResize);
-    return () => window.removeEventListener('resize', handleResize);
+    const timeout = DevSimulateSSR
+      ? window.setTimeout(updateWindowSize, 1000)
+      : undefined;
+
+    window.addEventListener('resize', updateWindowSize);
+
+    return () => {
+      window.removeEventListener('resize', updateWindowSize);
+      clearTimeout(timeout);
+    };
   }, []);
 
   return windowSize;
 }
 
-export {windowSizes};
 export default useWindowSize;

package/src/theme/prism-include-languages.ts

@@ -12,12 +12,13 @@ import type * as PrismNamespace from 'prismjs';
 const prismIncludeLanguages = (PrismObject: typeof PrismNamespace): void => {
   if (ExecutionEnvironment.canUseDOM) {
     const {
-      themeConfig: {prism: {additionalLanguages = []} = {}},
+      themeConfig: {prism = {}},
     } = siteConfig;
+    const {additionalLanguages = []} = prism as {additionalLanguages: string[]};
 
     window.Prism = PrismObject;
 
-    additionalLanguages.forEach((lang: string) => {
+    additionalLanguages.forEach((lang) => {
       require(`prismjs/components/prism-${lang}`); // eslint-disable-line
     });