@docusaurus/theme-common 2.0.0-beta.fc64c12e4 → 2.0.0

package/src/contexts/colorMode.tsx

@@ -0,0 +1,198 @@
+/**
+ * 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 ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import {ReactContextError} from '../utils/reactUtils';
+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/doc.tsx

@@ -0,0 +1,71 @@
+/**
+ * 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, type ReactNode, useContext} from 'react';
+import {ReactContextError} from '../utils/reactUtils';
+import type {PropDocContent} from '@docusaurus/plugin-content-docs';
+
+/**
+ * The React context value returned by the `useDoc()` hook.
+ * It contains useful data related to the currently browsed doc.
+ */
+export type DocContextValue = Pick<
+  PropDocContent,
+  'metadata' | 'frontMatter' | 'toc' | 'assets' | 'contentTitle'
+>;
+
+const Context = React.createContext<DocContextValue | null>(null);
+
+/**
+ * Note: we don't use `PropDoc` as context value on purpose. Metadata is
+ * currently stored inside the MDX component, but we may want to change that in
+ * the future. This layer is a good opportunity to decouple storage from
+ * consuming API, potentially allowing us to provide metadata as both props and
+ * route context without duplicating the chunks in the future.
+ */
+function useContextValue(content: PropDocContent): DocContextValue {
+  return useMemo(
+    () => ({
+      metadata: content.metadata,
+      frontMatter: content.frontMatter,
+      assets: content.assets,
+      contentTitle: content.contentTitle,
+      toc: content.toc,
+    }),
+    [content],
+  );
+}
+
+/**
+ * This is a very thin layer around the `content` received from the MDX loader.
+ * It provides metadata about the doc to the children tree.
+ */
+export function DocProvider({
+  children,
+  content,
+}: {
+  children: ReactNode;
+  content: PropDocContent;
+}): JSX.Element {
+  const contextValue = useContextValue(content);
+  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+/**
+ * Returns the data of the currently browsed doc. Gives access to the doc's MDX
+ * Component, front matter, metadata, TOC, etc. When swizzling a low-level
+ * component (e.g. the "Edit this page" link) and you need some extra metadata,
+ * you don't have to drill the props all the way through the component tree:
+ * simply use this hook instead.
+ */
+export function useDoc(): DocContextValue {
+  const doc = useContext(Context);
+  if (doc === null) {
+    throw new ReactContextError('DocProvider');
+  }
+  return doc;
+}

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,251 @@
+/**
+ * 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 {
+  useAllDocsData,
+  useDocsData,
+  type GlobalPluginData,
+  type GlobalVersion,
+} from '@docusaurus/plugin-content-docs/client';
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
+import {
+  useThemeConfig,
+  type DocsVersionPersistence,
+} from '../utils/useThemeConfig';
+import {isDocsPluginEnabled} from '../utils/docsUtils';
+import {ReactContextError} from '../utils/reactUtils';
+import {createStorageSlot} from '../utils/storageUtils';
+
+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: ReactNode;
+}): 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 {ReactContextError} from '../utils/reactUtils';
+import type {PropSidebar} from '@docusaurus/plugin-content-docs';
+
+// 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;
+}

package/src/contexts/docsVersion.tsx

@@ -0,0 +1,36 @@
+/**
+ * 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, useContext} from 'react';
+import {ReactContextError} from '../utils/reactUtils';
+import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
+
+const Context = React.createContext<PropVersionMetadata | null>(null);
+
+/**
+ * Provide the current version's metadata to your children.
+ */
+export function DocsVersionProvider({
+  children,
+  version,
+}: {
+  children: ReactNode;
+  version: PropVersionMetadata | null;
+}): JSX.Element {
+  return <Context.Provider value={version}>{children}</Context.Provider>;
+}
+
+/**
+ * Gets the version metadata of the current doc page.
+ */
+export function useDocsVersion(): PropVersionMetadata {
+  const version = useContext(Context);
+  if (version === null) {
+    throw new ReactContextError('DocsVersionProvider');
+  }
+  return version;
+}