@docusaurus/theme-common 3.7.0 → 3.8.0-canary-6327

package/src/contexts/colorMode.tsx

@@ -11,21 +11,52 @@ import React, {
   useEffect,
   useContext,
   useMemo,
-  useRef,
   type ReactNode,
 } from 'react';
-import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import {ReactContextError} from '../utils/reactUtils';
 import {createStorageSlot} from '../utils/storageUtils';
 import {useThemeConfig} from '../utils/useThemeConfig';
 
+// The "effective" color mode
+export type ColorMode = 'light' | 'dark';
+
+// The color mode explicitly chosen by the user
+// null => no choice has been made, or the choice has been reverted to OS value
+export type ColorModeChoice = ColorMode | null;
+
+function getSystemColorMode(): ColorMode {
+  return window.matchMedia('(prefers-color-scheme: dark)').matches
+    ? 'dark'
+    : 'light';
+}
+
+function subscribeToMedia(
+  query: string,
+  listener: (event: MediaQueryListEvent) => void,
+): () => void {
+  const mql = window.matchMedia(query);
+  mql.addEventListener('change', listener);
+  return () => mql.removeEventListener('change', listener);
+}
+
+function subscribeToSystemColorModeChange(
+  onChange: (newSystemColorMode: ColorMode) => void,
+): () => void {
+  return subscribeToMedia('(prefers-color-scheme: dark)', () =>
+    onChange(getSystemColorMode()),
+  );
+}
+
 type ContextValue = {
-  /** Current color mode. */
+  /** The effective color mode. */
   readonly colorMode: ColorMode;
+  /** The explicitly chosen color mode */
+  readonly colorModeChoice: ColorModeChoice;
   /** Set new color mode. */
-  readonly setColorMode: (colorMode: ColorMode) => void;
+  readonly setColorMode: (colorMode: ColorModeChoice) => void;
 
-  // TODO legacy APIs kept for retro-compatibility: deprecate them
+  // TODO Docusaurus v4
+  //  legacy APIs kept for retro-compatibility: deprecate them
   readonly isDarkTheme: boolean;
   readonly setLightTheme: () => void;
   readonly setDarkTheme: () => void;
@@ -36,33 +67,91 @@ const Context = React.createContext<ContextValue | undefined>(undefined);
 const ColorModeStorageKey = 'theme';
 const ColorModeStorage = createStorageSlot(ColorModeStorageKey);
 
-const ColorModes = {
-  light: 'light',
-  dark: 'dark',
-} as const;
-
-export type ColorMode = (typeof ColorModes)[keyof typeof ColorModes];
+// We use data-theme-choice="system", not an absent attribute
+// This is easier to handle for users with CSS
+const SystemAttribute = 'system';
 
 // Ensure to always return a valid colorMode even if input is invalid
-const coerceToColorMode = (colorMode?: string | null): ColorMode =>
-  colorMode === ColorModes.dark ? ColorModes.dark : ColorModes.light;
+const coerceToColorMode = (colorMode: string | null): ColorMode =>
+  colorMode === 'dark' ? 'dark' : 'light';
+const coerceToColorModeChoice = (colorMode: string | null): ColorModeChoice =>
+  colorMode === null || colorMode === SystemAttribute
+    ? null
+    : coerceToColorMode(colorMode);
+
+const ColorModeAttribute = {
+  get: () => {
+    return coerceToColorMode(
+      document.documentElement.getAttribute('data-theme'),
+    );
+  },
+  set: (colorMode: ColorMode) => {
+    document.documentElement.setAttribute(
+      'data-theme',
+      coerceToColorMode(colorMode),
+    );
+  },
+};
 
-const getInitialColorMode = (defaultMode: ColorMode | undefined): ColorMode =>
-  ExecutionEnvironment.canUseDOM
-    ? coerceToColorMode(document.documentElement.getAttribute('data-theme'))
-    : coerceToColorMode(defaultMode);
+const ColorModeChoiceAttribute = {
+  get: () => {
+    return coerceToColorModeChoice(
+      document.documentElement.getAttribute('data-theme-choice'),
+    );
+  },
+  set: (colorMode: ColorModeChoice) => {
+    document.documentElement.setAttribute(
+      'data-theme-choice',
+      coerceToColorModeChoice(colorMode) ?? SystemAttribute,
+    );
+  },
+};
 
-const storeColorMode = (newColorMode: ColorMode) => {
-  ColorModeStorage.set(coerceToColorMode(newColorMode));
+const persistColorModeChoice = (newColorMode: ColorModeChoice) => {
+  if (newColorMode === null) {
+    ColorModeStorage.del();
+  } else {
+    ColorModeStorage.set(coerceToColorMode(newColorMode));
+  }
 };
 
+// The color mode state is initialized in useEffect on purpose
+// to avoid a React hydration mismatch errors
+// The useColorMode() hook value lags behind on purpose
+// This helps users avoid hydration mismatch errors in their code
+// See also https://github.com/facebook/docusaurus/issues/7986
+function useColorModeState() {
+  const {
+    colorMode: {defaultMode},
+  } = useThemeConfig();
+
+  const [colorMode, setColorModeState] = useState<ColorMode>(defaultMode);
+  const [colorModeChoice, setColorModeChoiceState] =
+    useState<ColorModeChoice>(null);
+
+  useEffect(() => {
+    setColorModeState(ColorModeAttribute.get());
+    setColorModeChoiceState(ColorModeChoiceAttribute.get());
+  }, []);
+
+  return {
+    colorMode,
+    setColorModeState,
+    colorModeChoice,
+    setColorModeChoiceState,
+  } as const;
+}
+
 function useContextValue(): ContextValue {
   const {
     colorMode: {defaultMode, disableSwitch, respectPrefersColorScheme},
   } = useThemeConfig();
-  const [colorMode, setColorModeState] = useState(
-    getInitialColorMode(defaultMode),
-  );
+  const {
+    colorMode,
+    setColorModeState,
+    colorModeChoice,
+    setColorModeChoiceState,
+  } = useColorModeState();
 
   useEffect(() => {
     // A site is deployed without disableSwitch
@@ -75,78 +164,70 @@ function useContextValue(): ContextValue {
   }, [disableSwitch]);
 
   const setColorMode = useCallback(
-    (newColorMode: ColorMode | null, options: {persist?: boolean} = {}) => {
+    (
+      newColorModeChoice: ColorModeChoice,
+      options: {persist?: boolean} = {},
+    ) => {
       const {persist = true} = options;
-      if (newColorMode) {
+
+      // Reset to system/default color mode
+      if (newColorModeChoice === null) {
+        // Set the effective color
+        const newColorMode = respectPrefersColorScheme
+          ? getSystemColorMode()
+          : defaultMode;
+        ColorModeAttribute.set(newColorMode);
         setColorModeState(newColorMode);
-        if (persist) {
-          storeColorMode(newColorMode);
-        }
-      } else {
-        if (respectPrefersColorScheme) {
-          setColorModeState(
-            window.matchMedia('(prefers-color-scheme: dark)').matches
-              ? ColorModes.dark
-              : ColorModes.light,
-          );
-        } else {
-          setColorModeState(defaultMode);
-        }
-        ColorModeStorage.del();
+        // Set the chosen color
+        ColorModeChoiceAttribute.set(null);
+        setColorModeChoiceState(null);
+      }
+      // Happy case, when an explicit color is provided
+      else {
+        ColorModeAttribute.set(newColorModeChoice);
+        ColorModeChoiceAttribute.set(newColorModeChoice);
+        setColorModeState(newColorModeChoice);
+        setColorModeChoiceState(newColorModeChoice);
+      }
+
+      if (persist) {
+        persistColorModeChoice(newColorModeChoice);
       }
     },
-    [respectPrefersColorScheme, defaultMode],
+    [
+      setColorModeState,
+      setColorModeChoiceState,
+      respectPrefersColorScheme,
+      defaultMode,
+    ],
   );
 
+  // Synchronize theme color/choice mode with browser storage
   useEffect(() => {
-    document.documentElement.setAttribute(
-      'data-theme',
-      coerceToColorMode(colorMode),
-    );
-  }, [colorMode]);
+    return ColorModeStorage.listen((e) => {
+      setColorMode(coerceToColorModeChoice(e.newValue));
+    });
+  }, [setColorMode]);
 
+  // Synchronize theme color with system color
   useEffect(() => {
-    if (disableSwitch) {
+    if (colorModeChoice !== null || !respectPrefersColorScheme) {
       return undefined;
     }
-    const onChange = (e: StorageEvent) => {
-      if (e.key !== ColorModeStorageKey) {
-        return;
-      }
-      const storedColorMode = ColorModeStorage.get();
-      if (storedColorMode !== null) {
-        setColorMode(coerceToColorMode(storedColorMode));
-      }
-    };
-    window.addEventListener('storage', onChange);
-    return () => window.removeEventListener('storage', onChange);
-  }, [disableSwitch, setColorMode]);
-
-  // PCS is coerced to light mode when printing, which causes the color mode to
-  // be reset to dark when exiting print mode, disregarding user settings. When
-  // the listener fires only because of a print/screen switch, we don't change
-  // color mode. See https://github.com/facebook/docusaurus/pull/6490
-  const previousMediaIsPrint = useRef(false);
-
-  useEffect(() => {
-    if (disableSwitch && !respectPrefersColorScheme) {
-      return undefined;
-    }
-    const mql = window.matchMedia('(prefers-color-scheme: dark)');
-    const onChange = () => {
-      if (window.matchMedia('print').matches || previousMediaIsPrint.current) {
-        previousMediaIsPrint.current = window.matchMedia('print').matches;
-        return;
-      }
-      setColorMode(null);
-    };
-    mql.addListener(onChange);
-    return () => mql.removeListener(onChange);
-  }, [setColorMode, disableSwitch, respectPrefersColorScheme]);
+    return subscribeToSystemColorModeChange((newSystemColorMode) => {
+      // Note: we don't use "setColorMode" on purpose
+      // The system changes should never be considered an explicit theme choice
+      // They only affect the "effective" color, and should never be persisted
+      // Note: this listener also fire when printing, see https://github.com/facebook/docusaurus/pull/6490
+      setColorModeState(newSystemColorMode);
+      ColorModeAttribute.set(newSystemColorMode);
+    });
+  }, [respectPrefersColorScheme, colorModeChoice, setColorModeState]);
 
   return useMemo(
     () => ({
       colorMode,
+      colorModeChoice,
       setColorMode,
       get isDarkTheme() {
         if (process.env.NODE_ENV === 'development') {
@@ -154,7 +235,7 @@ function useContextValue(): ContextValue {
             '`useColorMode().isDarkTheme` is deprecated. Please use `useColorMode().colorMode === "dark"` instead.',
           );
         }
-        return colorMode === ColorModes.dark;
+        return colorMode === 'dark';
       },
       setLightTheme() {
         if (process.env.NODE_ENV === 'development') {
@@ -162,7 +243,7 @@ function useContextValue(): ContextValue {
             '`useColorMode().setLightTheme` is deprecated. Please use `useColorMode().setColorMode("light")` instead.',
           );
         }
-        setColorMode(ColorModes.light);
+        setColorMode('light');
       },
       setDarkTheme() {
         if (process.env.NODE_ENV === 'development') {
@@ -170,10 +251,10 @@ function useContextValue(): ContextValue {
             '`useColorMode().setDarkTheme` is deprecated. Please use `useColorMode().setColorMode("dark")` instead.',
           );
         }
-        setColorMode(ColorModes.dark);
+        setColorMode('dark');
       },
     }),
-    [colorMode, setColorMode],
+    [colorMode, colorModeChoice, setColorMode],
   );
 }
 

package/src/contexts/navbarMobileSidebar.tsx

@@ -53,18 +53,6 @@ function useContextValue(): ContextValue {
 
   const [shown, setShown] = useState(false);
 
-  // Close mobile sidebar on navigation pop
-  // Most likely firing when using the Android back button (but not only)
-  useHistoryPopHandler(() => {
-    if (shown) {
-      setShown(false);
-      // Prevent pop navigation; seems desirable enough
-      // See https://github.com/facebook/docusaurus/pull/5462#issuecomment-911699846
-      return false;
-    }
-    return undefined;
-  });
-
   const toggle = useCallback(() => {
     setShown((s) => !s);
   }, []);
@@ -81,13 +69,45 @@ function useContextValue(): ContextValue {
   );
 }
 
+// A component hook wrapper enables conditional rendering
+// See reason here: https://github.com/facebook/docusaurus/issues/10988
+function OnHistoryPop({
+  handler,
+}: {
+  handler: Parameters<typeof useHistoryPopHandler>[0];
+}) {
+  useHistoryPopHandler(handler);
+  return null;
+}
+
 export function NavbarMobileSidebarProvider({
   children,
 }: {
   children: ReactNode;
 }): ReactNode {
   const value = useContextValue();
-  return <Context.Provider value={value}>{children}</Context.Provider>;
+  return (
+    <>
+      {
+        // Close mobile sidebar on navigation pop
+        // Most likely firing when using the Android back button (but not only)
+        // Important: we can only have a single history blocker at a time
+        // That's why this needs to be rendered conditionally
+        // See bug report https://github.com/facebook/docusaurus/issues/10988
+        value.shown && (
+          <OnHistoryPop
+            handler={() => {
+              value.toggle();
+              // Prevent pop navigation; seems desirable enough
+              // See https://github.com/facebook/docusaurus/pull/5462#issuecomment-911699846
+              return false;
+            }}
+          />
+        )
+      }
+      <Context.Provider value={value}>{children}</Context.Provider>
+    </>
+  );
 }
 
 export function useNavbarMobileSidebar(): ContextValue {

package/src/hooks/useCodeWordWrap.ts

@@ -52,12 +52,14 @@ function useTabBecameVisibleCallback(
   );
 }
 
-export function useCodeWordWrap(): {
+export type WordWrap = {
   readonly codeBlockRef: RefObject<HTMLPreElement>;
   readonly isEnabled: boolean;
   readonly isCodeScrollable: boolean;
   readonly toggle: () => void;
-} {
+};
+
+export function useCodeWordWrap(): WordWrap {
   const [isEnabled, setIsEnabled] = useState(false);
   const [isCodeScrollable, setIsCodeScrollable] = useState<boolean>(false);
   const codeBlockRef = useRef<HTMLPreElement>(null);

package/src/index.ts

@@ -33,7 +33,7 @@ export function useDocsPreferredVersion(...args: unknown[]): unknown {
 export function useContextualSearchFilters() {
   const {i18n} = useDocusaurusContext();
   const docsTags =
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, react-compiler/react-compiler
     require('@docusaurus/plugin-content-docs/client').useDocsContextualSearchTags();
   const tags = [DEFAULT_SEARCH_TAG, ...docsTags];
   return {locale: i18n.currentLocale, tags};

package/src/internal.ts

@@ -34,15 +34,27 @@ export {ColorModeProvider} from './contexts/colorMode';
 export {useAlternatePageUtils} from './utils/useAlternatePageUtils';
 
 export {
+  type CodeBlockMetadata,
+  createCodeBlockMetadata,
+  getPrismCssVariables,
+  CodeBlockContextProvider,
+  useCodeBlockContext,
+
+  // TODO Docusaurus v4: remove, only kept for internal retro-compatibility
+  //  See https://github.com/facebook/docusaurus/pull/11153
   parseCodeBlockTitle,
-  parseLanguage,
+  parseClassNameLanguage as parseLanguage,
   parseLines,
+  getLineNumbersStart,
   containsLineNumbers,
 } from './utils/codeBlockUtils';
 
 export {DEFAULT_SEARCH_TAG} from './utils/searchUtils';
 
-export {useTitleFormatter} from './utils/generalUtils';
+export {
+  TitleFormatterProvider,
+  useTitleFormatter,
+} from './utils/titleFormatterUtils';
 
 export {useLocationChange} from './utils/useLocationChange';
 
@@ -88,7 +100,6 @@ export {
 } from './hooks/useKeyboardNavigation';
 export {useLockBodyScroll} from './hooks/useLockBodyScroll';
 export {useCodeWordWrap} from './hooks/useCodeWordWrap';
-export {getPrismCssVariables} from './utils/codeBlockUtils';
 export {useBackToTopButton} from './hooks/useBackToTopButton';
 
 export {

package/src/utils/ThemeClassNames.ts

@@ -27,8 +27,10 @@ export const ThemeClassNames = {
 
     mdxPage: 'mdx-page',
   },
+
+  // TODO Docusaurus v4: remove old classes?
   wrapper: {
-    main: 'main-wrapper',
+    main: 'main-wrapper', // replaced by theme-layout-main
     // TODO these wrapper class names are now quite useless
     // TODO do breaking change later in 3.0
     // we already add plugin name/id class on <html>: that's enough
@@ -36,6 +38,7 @@ export const ThemeClassNames = {
     docsPages: 'docs-wrapper',
     mdxPages: 'mdx-wrapper',
   },
+
   common: {
     editThisPage: 'theme-edit-this-page',
     lastUpdated: 'theme-last-updated',
@@ -47,8 +50,28 @@ export const ThemeClassNames = {
 
     admonitionType: (type: string) => `theme-admonition-${type}`,
   },
+
+  announcementBar: {
+    container: 'theme-announcement-bar',
+  },
+
   layout: {
-    // TODO add other stable classNames here
+    navbar: {
+      container: 'theme-layout-navbar',
+      containerLeft: 'theme-layout-navbar-left',
+      containerRight: 'theme-layout-navbar-right',
+      mobileSidebar: {
+        container: 'theme-layout-navbar-sidebar',
+        panel: 'theme-layout-navbar-sidebar-panel',
+      },
+    },
+    main: {
+      container: 'theme-layout-main',
+    },
+    footer: {
+      container: 'theme-layout-footer',
+      column: 'theme-layout-footer-column',
+    },
   },
 
   /**