@docusaurus/theme-common 2.0.0-beta.2 → 2.0.0-beta.20

package/src/{utils/announcementBarUtils.tsx → contexts/announcementBar.tsx}

@@ -10,13 +10,13 @@ import React, {
   useEffect,
   useCallback,
   useMemo,
-  ReactNode,
   useContext,
-  createContext,
+  type ReactNode,
 } from 'react';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {createStorageSlot} from './storageUtils';
-import {useThemeConfig} from './useThemeConfig';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {createStorageSlot} from '../utils/storageUtils';
+import {ReactContextError} from '../utils/reactUtils';
+import {useThemeConfig} from '../utils/useThemeConfig';
 
 export const AnnouncementBarDismissStorageKey =
   'docusaurus.announcement.dismiss';
@@ -32,22 +32,28 @@ const isDismissedInStorage = () =>
 const setDismissedInStorage = (bool: boolean) =>
   AnnouncementBarDismissStorage.set(String(bool));
 
-type AnnouncementBarAPI = {
-  readonly isClosed: boolean;
+type ContextValue = {
+  /** Whether the announcement bar should be displayed. */
+  readonly isActive: boolean;
+  /**
+   * Callback fired when the user closes the announcement. Will be saved.
+   */
   readonly close: () => void;
 };
 
-const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
+const Context = React.createContext<ContextValue | null>(null);
+
+function useContextValue(): ContextValue {
   const {announcementBar} = useThemeConfig();
-  const {isClient} = useDocusaurusContext();
+  const isBrowser = useIsBrowser();
 
-  const [isClosed, setClosed] = useState(() => {
-    return isClient
-      ? // On client navigation: init with localstorage value
+  const [isClosed, setClosed] = useState(() =>
+    isBrowser
+      ? // On client navigation: init with local storage value
         isDismissedInStorage()
       : // On server/hydration: always visible to prevent layout shifts (will be hidden with css if needed)
-        false;
-  });
+        false,
+  );
   // Update state after hydration
   useEffect(() => {
     setClosed(isDismissedInStorage());
@@ -66,8 +72,9 @@ const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
 
     let viewedId = IdStorage.get();
 
-    // retrocompatibility due to spelling mistake of default id
+    // Retrocompatibility due to spelling mistake of default id
     // see https://github.com/facebook/docusaurus/issues/3338
+    // cSpell:ignore annoucement
     if (viewedId === 'annoucement-bar') {
       viewedId = 'announcement-bar';
     }
@@ -83,33 +90,30 @@ const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
     if (isNewAnnouncement || !isDismissedInStorage()) {
       setClosed(false);
     }
-  }, []);
+  }, [announcementBar]);
 
-  return useMemo(() => {
-    return {
-      isClosed,
+  return useMemo(
+    () => ({
+      isActive: !!announcementBar && !isClosed,
       close: handleClose,
-    };
-  }, [isClosed]);
-};
-
-const AnnouncementBarContext = createContext<AnnouncementBarAPI | null>(null);
-
-export const AnnouncementBarProvider = ({children}: {children: ReactNode}) => {
-  const value = useAnnouncementBarContextValue();
-  return (
-    <AnnouncementBarContext.Provider value={value}>
-      {children}
-    </AnnouncementBarContext.Provider>
+    }),
+    [announcementBar, isClosed, handleClose],
   );
-};
-
-export const useAnnouncementBar = (): AnnouncementBarAPI => {
-  const api = useContext(AnnouncementBarContext);
+}
+
+export function AnnouncementBarProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const value = useContextValue();
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+export function useAnnouncementBar(): ContextValue {
+  const api = useContext(Context);
   if (!api) {
-    throw new Error(
-      'useAnnouncementBar(): AnnouncementBar not found in React context: make sure to use the AnnouncementBarProvider on top of the tree',
-    );
+    throw new ReactContextError('AnnouncementBarProvider');
   }
   return api;
-};
+}

package/src/contexts/colorMode.tsx

@@ -0,0 +1,199 @@
+/**
+ * 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,
+  useCallback,
+  useEffect,
+  useContext,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react';
+import {ReactContextError} from '../utils/reactUtils';
+
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import {createStorageSlot} from '../utils/storageUtils';
+import {useThemeConfig} from '../utils/useThemeConfig';
+
+type ContextValue = {
+  /** Current color mode. */
+  readonly colorMode: ColorMode;
+  /** Set new color mode. */
+  readonly setColorMode: (colorMode: ColorMode) => void;
+
+  // TODO legacy APIs kept for retro-compatibility: deprecate them
+  readonly isDarkTheme: boolean;
+  readonly setLightTheme: () => void;
+  readonly setDarkTheme: () => void;
+};
+
+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];
+
+// 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 getInitialColorMode = (defaultMode: ColorMode | undefined): ColorMode =>
+  ExecutionEnvironment.canUseDOM
+    ? coerceToColorMode(document.documentElement.getAttribute('data-theme'))
+    : coerceToColorMode(defaultMode);
+
+const storeColorMode = (newColorMode: ColorMode) => {
+  ColorModeStorage.set(coerceToColorMode(newColorMode));
+};
+
+function useContextValue(): ContextValue {
+  const {
+    colorMode: {defaultMode, disableSwitch, respectPrefersColorScheme},
+  } = useThemeConfig();
+  const [colorMode, setColorModeState] = useState(
+    getInitialColorMode(defaultMode),
+  );
+
+  useEffect(() => {
+    // A site is deployed without disableSwitch
+    // => User visits the site and has a persisted value
+    // => Site later enabled disableSwitch
+    // => Clear the previously stored value to apply the site's setting
+    if (disableSwitch) {
+      ColorModeStorage.del();
+    }
+  }, [disableSwitch]);
+
+  const setColorMode = useCallback(
+    (newColorMode: ColorMode | null, options: {persist?: boolean} = {}) => {
+      const {persist = true} = options;
+      if (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();
+      }
+    },
+    [respectPrefersColorScheme, defaultMode],
+  );
+
+  useEffect(() => {
+    document.documentElement.setAttribute(
+      'data-theme',
+      coerceToColorMode(colorMode),
+    );
+  }, [colorMode]);
+
+  useEffect(() => {
+    if (disableSwitch) {
+      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 useMemo(
+    () => ({
+      colorMode,
+      setColorMode,
+      get isDarkTheme() {
+        if (process.env.NODE_ENV === 'development') {
+          console.error(
+            '`useColorMode().isDarkTheme` is deprecated. Please use `useColorMode().colorMode === "dark"` instead.',
+          );
+        }
+        return colorMode === ColorModes.dark;
+      },
+      setLightTheme() {
+        if (process.env.NODE_ENV === 'development') {
+          console.error(
+            '`useColorMode().setLightTheme` is deprecated. Please use `useColorMode().setColorMode("light")` instead.',
+          );
+        }
+        setColorMode(ColorModes.light);
+      },
+      setDarkTheme() {
+        if (process.env.NODE_ENV === 'development') {
+          console.error(
+            '`useColorMode().setDarkTheme` is deprecated. Please use `useColorMode().setColorMode("dark")` instead.',
+          );
+        }
+        setColorMode(ColorModes.dark);
+      },
+    }),
+    [colorMode, setColorMode],
+  );
+}
+
+export function ColorModeProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const value = useContextValue();
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+export function useColorMode(): ContextValue {
+  const context = useContext(Context);
+  if (context == null) {
+    throw new ReactContextError(
+      'ColorModeProvider',
+      'Please see https://docusaurus.io/docs/api/themes/configuration#use-color-mode.',
+    );
+  }
+  return context;
+}

package/src/contexts/docSidebarItemsExpandedState.tsx

@@ -0,0 +1,55 @@
+/**
+ * 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, {type ReactNode, useMemo, useState, useContext} from 'react';
+import {ReactContextError} from '../utils/reactUtils';
+
+type ContextValue = {
+  /**
+   * The item that the user last opened, `null` when there's none open. On
+   * initial render, it will always be `null`, which doesn't necessarily mean
+   * there's no category open (can have 0, 1, or many being initially open).
+   */
+  expandedItem: number | null;
+  /**
+   * Set the currently expanded item, when the user opens one. Set the value to
+   * `null` when the user closes an open category.
+   */
+  setExpandedItem: (a: number | null) => void;
+};
+
+const EmptyContext: unique symbol = Symbol('EmptyContext');
+const Context = React.createContext<ContextValue | typeof EmptyContext>(
+  EmptyContext,
+);
+
+/**
+ * Should be used to wrap one sidebar category level. This provider syncs the
+ * expanded states of all sibling categories, and categories can choose to
+ * collapse itself if another one is expanded.
+ */
+export function DocSidebarItemsExpandedStateProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const [expandedItem, setExpandedItem] = useState<number | null>(null);
+  const contextValue = useMemo(
+    () => ({expandedItem, setExpandedItem}),
+    [expandedItem],
+  );
+
+  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+export function useDocSidebarItemsExpandedState(): ContextValue {
+  const value = useContext(Context);
+  if (value === EmptyContext) {
+    throw new ReactContextError('DocSidebarItemsExpandedStateProvider');
+  }
+  return value;
+}

package/src/contexts/docsPreferredVersion.tsx

@@ -0,0 +1,253 @@
+/**
+ * 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, {
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  useCallback,
+  type ReactNode,
+} from 'react';
+import {
+  useThemeConfig,
+  type DocsVersionPersistence,
+} from '../utils/useThemeConfig';
+import {isDocsPluginEnabled} from '../utils/docsUtils';
+import {ReactContextError} from '../utils/reactUtils';
+import {createStorageSlot} from '../utils/storageUtils';
+
+import {
+  useAllDocsData,
+  useDocsData,
+  type GlobalPluginData,
+  type GlobalVersion,
+} from '@docusaurus/plugin-content-docs/client';
+
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
+
+const storageKey = (pluginId: string) => `docs-preferred-version-${pluginId}`;
+
+const DocsPreferredVersionStorage = {
+  save: (
+    pluginId: string,
+    persistence: DocsVersionPersistence,
+    versionName: string,
+  ): void => {
+    createStorageSlot(storageKey(pluginId), {persistence}).set(versionName);
+  },
+
+  read: (
+    pluginId: string,
+    persistence: DocsVersionPersistence,
+  ): string | null =>
+    createStorageSlot(storageKey(pluginId), {persistence}).get(),
+
+  clear: (pluginId: string, persistence: DocsVersionPersistence): void => {
+    createStorageSlot(storageKey(pluginId), {persistence}).del();
+  },
+};
+
+type DocsPreferredVersionName = string | null;
+
+/** State for a single docs plugin instance */
+type DocsPreferredVersionPluginState = {
+  preferredVersionName: DocsPreferredVersionName;
+};
+
+/**
+ * We need to store the state in storage globally, with one preferred version
+ * per docs plugin instance.
+ */
+type DocsPreferredVersionState = {
+  [pluginId: string]: DocsPreferredVersionPluginState;
+};
+
+/**
+ * Initial state is always null as we can't read local storage from node SSR
+ */
+const getInitialState = (pluginIds: string[]): DocsPreferredVersionState =>
+  Object.fromEntries(pluginIds.map((id) => [id, {preferredVersionName: null}]));
+
+/**
+ * Read storage for all docs plugins, assigning each doc plugin a preferred
+ * version (if found)
+ */
+function readStorageState({
+  pluginIds,
+  versionPersistence,
+  allDocsData,
+}: {
+  pluginIds: string[];
+  versionPersistence: DocsVersionPersistence;
+  allDocsData: {[pluginId: string]: GlobalPluginData};
+}): DocsPreferredVersionState {
+  /**
+   * The storage value we read might be stale, and belong to a version that does
+   * not exist in the site anymore. In such case, we remove the storage value to
+   * avoid downstream errors.
+   */
+  function restorePluginState(
+    pluginId: string,
+  ): DocsPreferredVersionPluginState {
+    const preferredVersionNameUnsafe = DocsPreferredVersionStorage.read(
+      pluginId,
+      versionPersistence,
+    );
+    const pluginData = allDocsData[pluginId]!;
+    const versionExists = pluginData.versions.some(
+      (version) => version.name === preferredVersionNameUnsafe,
+    );
+    if (versionExists) {
+      return {preferredVersionName: preferredVersionNameUnsafe};
+    }
+    DocsPreferredVersionStorage.clear(pluginId, versionPersistence);
+    return {preferredVersionName: null};
+  }
+  return Object.fromEntries(
+    pluginIds.map((id) => [id, restorePluginState(id)]),
+  );
+}
+
+function useVersionPersistence(): DocsVersionPersistence {
+  return useThemeConfig().docs.versionPersistence;
+}
+
+type ContextValue = [
+  state: DocsPreferredVersionState,
+  api: {
+    savePreferredVersion: (pluginId: string, versionName: string) => void;
+  },
+];
+
+const Context = React.createContext<ContextValue | null>(null);
+
+function useContextValue(): ContextValue {
+  const allDocsData = useAllDocsData();
+  const versionPersistence = useVersionPersistence();
+  const pluginIds = useMemo(() => Object.keys(allDocsData), [allDocsData]);
+
+  // Initial state is empty, as we can't read browser storage in node/SSR
+  const [state, setState] = useState(() => getInitialState(pluginIds));
+
+  // On mount, we set the state read from browser storage
+  useEffect(() => {
+    setState(readStorageState({allDocsData, versionPersistence, pluginIds}));
+  }, [allDocsData, versionPersistence, pluginIds]);
+
+  // The API that we expose to consumer hooks (memo for constant object)
+  const api = useMemo(() => {
+    function savePreferredVersion(pluginId: string, versionName: string) {
+      DocsPreferredVersionStorage.save(
+        pluginId,
+        versionPersistence,
+        versionName,
+      );
+      setState((s) => ({
+        ...s,
+        [pluginId]: {preferredVersionName: versionName},
+      }));
+    }
+
+    return {
+      savePreferredVersion,
+    };
+  }, [versionPersistence]);
+
+  return [state, api];
+}
+
+function DocsPreferredVersionContextProviderUnsafe({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const value = useContextValue();
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+/**
+ * This is a maybe-layer. If the docs plugin is not enabled, this provider is a
+ * simple pass-through.
+ */
+export function DocsPreferredVersionContextProvider({
+  children,
+}: {
+  children: JSX.Element;
+}): JSX.Element {
+  if (isDocsPluginEnabled) {
+    return (
+      <DocsPreferredVersionContextProviderUnsafe>
+        {children}
+      </DocsPreferredVersionContextProviderUnsafe>
+    );
+  }
+  return children;
+}
+
+function useDocsPreferredVersionContext(): ContextValue {
+  const value = useContext(Context);
+  if (!value) {
+    throw new ReactContextError('DocsPreferredVersionContextProvider');
+  }
+  return value;
+}
+
+/**
+ * Returns a read-write interface to a plugin's preferred version. The
+ * "preferred version" is defined as the last version that the user visited.
+ * For example, if a user is using v3, even when v4 is later published, the user
+ * would still be browsing v3 docs when she opens the website next time. Note,
+ * the `preferredVersion` attribute will always be `null` before mount.
+ */
+export function useDocsPreferredVersion(
+  pluginId: string | undefined = DEFAULT_PLUGIN_ID,
+): {
+  preferredVersion: GlobalVersion | null;
+  savePreferredVersionName: (versionName: string) => void;
+} {
+  const docsData = useDocsData(pluginId);
+  const [state, api] = useDocsPreferredVersionContext();
+
+  const {preferredVersionName} = state[pluginId]!;
+
+  const preferredVersion =
+    docsData.versions.find(
+      (version) => version.name === preferredVersionName,
+    ) ?? null;
+
+  const savePreferredVersionName = useCallback(
+    (versionName: string) => {
+      api.savePreferredVersion(pluginId, versionName);
+    },
+    [api, pluginId],
+  );
+
+  return {preferredVersion, savePreferredVersionName};
+}
+
+export function useDocsPreferredVersionByPluginId(): {
+  [pluginId: string]: GlobalVersion | null;
+} {
+  const allDocsData = useAllDocsData();
+  const [state] = useDocsPreferredVersionContext();
+
+  function getPluginIdPreferredVersion(pluginId: string) {
+    const docsData = allDocsData[pluginId]!;
+    const {preferredVersionName} = state[pluginId]!;
+
+    return (
+      docsData.versions.find(
+        (version) => version.name === preferredVersionName,
+      ) ?? null
+    );
+  }
+  const pluginIds = Object.keys(allDocsData);
+  return Object.fromEntries(
+    pluginIds.map((id) => [id, getPluginIdPreferredVersion(id)]),
+  );
+}

package/src/contexts/docsSidebar.tsx

@@ -0,0 +1,50 @@
+/**
+ * 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, {useMemo, useContext, type ReactNode} from 'react';
+import type {PropSidebar} from '@docusaurus/plugin-content-docs';
+import {ReactContextError} from '../utils/reactUtils';
+
+// Using a Symbol because null is a valid context value (a doc with no sidebar)
+// Inspired by https://github.com/jamiebuilds/unstated-next/blob/master/src/unstated-next.tsx
+const EmptyContext: unique symbol = Symbol('EmptyContext');
+
+type ContextValue = {name: string; items: PropSidebar};
+
+const Context = React.createContext<ContextValue | null | typeof EmptyContext>(
+  EmptyContext,
+);
+
+/**
+ * Provide the current sidebar to your children.
+ */
+export function DocsSidebarProvider({
+  children,
+  name,
+  items,
+}: {
+  children: ReactNode;
+  name: string | undefined;
+  items: PropSidebar | undefined;
+}): JSX.Element {
+  const stableValue: ContextValue | null = useMemo(
+    () => (name && items ? {name, items} : null),
+    [name, items],
+  );
+  return <Context.Provider value={stableValue}>{children}</Context.Provider>;
+}
+
+/**
+ * Gets the sidebar that's currently displayed, or `null` if there isn't one
+ */
+export function useDocsSidebar(): ContextValue | null {
+  const value = useContext(Context);
+  if (value === EmptyContext) {
+    throw new ReactContextError('DocsSidebarProvider');
+  }
+  return value;
+}