@docusaurus/theme-common 2.0.0-beta.17 → 2.0.0-beta.18

package/src/contexts/docsPreferredVersion.tsx

@@ -0,0 +1,250 @@
+/**
+ * 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.
+ * 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,42 @@
+/**
+ * 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 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');
+
+const Context = React.createContext<PropSidebar | null | typeof EmptyContext>(
+  EmptyContext,
+);
+
+/**
+ * Provide the current sidebar to your children.
+ */
+export function DocsSidebarProvider({
+  children,
+  sidebar,
+}: {
+  children: ReactNode;
+  sidebar: PropSidebar | null;
+}): JSX.Element {
+  return <Context.Provider value={sidebar}>{children}</Context.Provider>;
+}
+
+/**
+ * Gets the sidebar that's currently displayed, or `null` if there isn't one
+ */
+export function useDocsSidebar(): PropSidebar | null {
+  const sidebar = useContext(Context);
+  if (sidebar === EmptyContext) {
+    throw new ReactContextError('DocsSidebarProvider');
+  }
+  return sidebar;
+}

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 type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
+import {ReactContextError} from '../utils/reactUtils';
+
+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;
+}

package/src/contexts/navbarMobileSidebar.tsx

@@ -0,0 +1,99 @@
+/**
+ * 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, {
+  useCallback,
+  useEffect,
+  useState,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import {useWindowSize} from '../hooks/useWindowSize';
+import {useHistoryPopHandler} from '../utils/historyUtils';
+import {useActivePlugin} from '@docusaurus/plugin-content-docs/client';
+import {useThemeConfig} from '../utils/useThemeConfig';
+import {ReactContextError} from '../utils/reactUtils';
+
+type ContextValue = {
+  /**
+   * Mobile sidebar should be disabled in case it's empty, i.e. no secondary
+   * menu + no navbar items). If disabled, the toggle button should not be
+   * displayed at all.
+   */
+  disabled: boolean;
+  /**
+   * Signals whether the actual sidebar should be displayed (contrary to
+   * `disabled` which is about the toggle button). Sidebar should not visible
+   * until user interaction to avoid SSR rendering.
+   */
+  shouldRender: boolean;
+  /** The displayed state. Can be toggled with the `toggle` callback. */
+  shown: boolean;
+  /** Toggle the `shown` attribute. */
+  toggle: () => void;
+};
+
+const Context = React.createContext<ContextValue | undefined>(undefined);
+
+function useIsNavbarMobileSidebarDisabled() {
+  const activeDocPlugin = useActivePlugin();
+  const {items} = useThemeConfig().navbar;
+  return items.length === 0 && !activeDocPlugin;
+}
+
+function useContextValue(): ContextValue {
+  const disabled = useIsNavbarMobileSidebarDisabled();
+  const windowSize = useWindowSize();
+
+  const shouldRender = !disabled && windowSize === 'mobile';
+
+  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);
+      // Should we prevent the navigation here?
+      // See https://github.com/facebook/docusaurus/pull/5462#issuecomment-911699846
+      return false; // prevent pop navigation
+    }
+    return undefined;
+  });
+
+  const toggle = useCallback(() => {
+    setShown((s) => !s);
+  }, []);
+
+  useEffect(() => {
+    if (windowSize === 'desktop') {
+      setShown(false);
+    }
+  }, [windowSize]);
+
+  return useMemo(
+    () => ({disabled, shouldRender, toggle, shown}),
+    [disabled, shouldRender, toggle, shown],
+  );
+}
+
+export function NavbarMobileSidebarProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const value = useContextValue();
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+export function useNavbarMobileSidebar(): ContextValue {
+  const context = React.useContext(Context);
+  if (context === undefined) {
+    throw new ReactContextError('NavbarMobileSidebarProvider');
+  }
+  return context;
+}

package/src/contexts/navbarSecondaryMenu.tsx

@@ -0,0 +1,170 @@
+/**
+ * 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,
+  useContext,
+  useEffect,
+  useMemo,
+  useCallback,
+  type ReactNode,
+  type ComponentType,
+} from 'react';
+import {ReactContextError, usePrevious} from '../utils/reactUtils';
+import {useNavbarMobileSidebar} from './navbarMobileSidebar';
+
+export type NavbarSecondaryMenuComponent<Props> = ComponentType<Props>;
+
+type State = {
+  shown: boolean;
+  content:
+    | {
+        component: NavbarSecondaryMenuComponent<object>;
+        props: object;
+      }
+    | {component: null; props: null};
+};
+
+const InitialState: State = {
+  shown: false,
+  content: {component: null, props: null},
+};
+
+type ContextValue = [
+  state: State,
+  setState: React.Dispatch<React.SetStateAction<State>>,
+];
+
+const Context = React.createContext<ContextValue | null>(null);
+
+function useContextValue(): ContextValue {
+  const mobileSidebar = useNavbarMobileSidebar();
+
+  const [state, setState] = useState<State>(InitialState);
+
+  const setShown = (shown: boolean) => setState((s) => ({...s, shown}));
+
+  const hasContent = state.content?.component !== null;
+  const previousHasContent = usePrevious(state.content?.component !== null);
+
+  // When content is become available for the first time (set in useEffect)
+  // we set this content to be shown!
+  useEffect(() => {
+    const contentBecameAvailable = hasContent && !previousHasContent;
+    if (contentBecameAvailable) {
+      setShown(true);
+    }
+  }, [hasContent, previousHasContent]);
+
+  // On sidebar close, secondary menu is set to be shown on next re-opening
+  // (if any secondary menu content available)
+  useEffect(() => {
+    if (!hasContent) {
+      setShown(false);
+      return;
+    }
+    if (!mobileSidebar.shown) {
+      setShown(true);
+    }
+  }, [mobileSidebar.shown, hasContent]);
+
+  return [state, setState];
+}
+
+export function NavbarSecondaryMenuProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const value = useContextValue();
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+function useNavbarSecondaryMenuContext(): ContextValue {
+  const value = useContext(Context);
+  if (value === null) {
+    throw new ReactContextError('MobileSecondaryMenuProvider');
+  }
+  return value;
+}
+
+function useShallowMemoizedObject<O>(obj: O) {
+  return useMemo(
+    () => obj,
+    // Is this safe?
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [...Object.keys(obj), ...Object.values(obj)],
+  );
+}
+
+/**
+ * This component renders nothing by itself, but it fills the placeholder in the
+ * generic secondary menu layout. This reduces coupling between the main layout
+ * and the specific page.
+ *
+ * This kind of feature is often called portal/teleport/gateway/outlet...
+ * Various unmaintained React libs exist. Most up-to-date one:
+ * https://github.com/gregberge/react-teleporter
+ * Not sure any of those is safe regarding concurrent mode.
+ */
+export function NavbarSecondaryMenuFiller<P extends object>({
+  component,
+  props,
+}: {
+  component: NavbarSecondaryMenuComponent<P>;
+  props: P;
+}): JSX.Element | null {
+  const [, setState] = useNavbarSecondaryMenuContext();
+
+  // To avoid useless context re-renders, props are memoized shallowly
+  const memoizedProps = useShallowMemoizedObject(props);
+
+  useEffect(() => {
+    // @ts-expect-error: context is not 100% type-safe but it's ok
+    setState((s) => ({...s, content: {component, props: memoizedProps}}));
+  }, [setState, component, memoizedProps]);
+
+  useEffect(
+    () => () => setState((s) => ({...s, component: null, props: null})),
+    [setState],
+  );
+
+  return null;
+}
+
+function renderElement(state: State): JSX.Element | undefined {
+  if (state.content?.component) {
+    const Comp = state.content.component;
+    return <Comp {...state.content.props} />;
+  }
+  return undefined;
+}
+
+/** Wires the logic for rendering the mobile navbar secondary menu. */
+export function useNavbarSecondaryMenu(): {
+  /** Whether secondary menu is displayed. */
+  shown: boolean;
+  /**
+   * Hide the secondary menu; fired either when hiding the entire sidebar, or
+   * when going back to the primary menu.
+   */
+  hide: () => void;
+  /** The content returned from the current secondary menu filler. */
+  content: JSX.Element | undefined;
+} {
+  const [state, setState] = useNavbarSecondaryMenuContext();
+
+  const hide = useCallback(
+    () => setState((s) => ({...s, shown: false})),
+    [setState],
+  );
+
+  return useMemo(
+    () => ({shown: state.shown, hide, content: renderElement(state)}),
+    [hide, state],
+  );
+}

package/src/{utils/tabGroupChoiceUtils.tsx → contexts/tabGroupChoice.tsx}

@@ -9,26 +9,25 @@ import React, {
   useState,
   useCallback,
   useEffect,
-  createContext,
   useMemo,
   useContext,
   type ReactNode,
 } from 'react';
-import {createStorageSlot, listStorageKeys} from './storageUtils';
-import {ReactContextError} from './reactUtils';
+import {createStorageSlot, listStorageKeys} from '../utils/storageUtils';
+import {ReactContextError} from '../utils/reactUtils';
 
 const TAB_CHOICE_PREFIX = 'docusaurus.tab.';
 
-type TabGroupChoiceContextValue = {
+type ContextValue = {
+  /** A map from `groupId` to the `value` of the saved choice. */
   readonly tabGroupChoices: {readonly [groupId: string]: string};
+  /** Set the new choice value of a group. */
   readonly setTabGroupChoices: (groupId: string, newChoice: string) => void;
 };
 
-const TabGroupChoiceContext = createContext<
-  TabGroupChoiceContextValue | undefined
->(undefined);
+const Context = React.createContext<ContextValue | undefined>(undefined);
 
-function useTabGroupChoiceContextValue(): TabGroupChoiceContextValue {
+function useContextValue(): ContextValue {
   const [tabGroupChoices, setChoices] = useState<{
     readonly [groupId: string]: string;
   }>({});
@@ -38,7 +37,7 @@ function useTabGroupChoiceContextValue(): TabGroupChoiceContextValue {
 
   useEffect(() => {
     try {
-      const localStorageChoices: Record<string, string> = {};
+      const localStorageChoices: {[groupId: string]: string} = {};
       listStorageKeys().forEach((storageKey) => {
         if (storageKey.startsWith(TAB_CHOICE_PREFIX)) {
           const groupId = storageKey.substring(TAB_CHOICE_PREFIX.length);
@@ -51,13 +50,18 @@ function useTabGroupChoiceContextValue(): TabGroupChoiceContextValue {
     }
   }, []);
 
-  return {
-    tabGroupChoices,
-    setTabGroupChoices: (groupId: string, newChoice: string) => {
+  const setTabGroupChoices = useCallback(
+    (groupId: string, newChoice: string) => {
       setChoices((oldChoices) => ({...oldChoices, [groupId]: newChoice}));
       setChoiceSyncWithLocalStorage(groupId, newChoice);
     },
-  };
+    [setChoiceSyncWithLocalStorage],
+  );
+
+  return useMemo(
+    () => ({tabGroupChoices, setTabGroupChoices}),
+    [tabGroupChoices, setTabGroupChoices],
+  );
 }
 
 export function TabGroupChoiceProvider({
@@ -65,23 +69,12 @@ export function TabGroupChoiceProvider({
 }: {
   children: ReactNode;
 }): JSX.Element {
-  const {tabGroupChoices, setTabGroupChoices} = useTabGroupChoiceContextValue();
-  const contextValue = useMemo(
-    () => ({
-      tabGroupChoices,
-      setTabGroupChoices,
-    }),
-    [tabGroupChoices, setTabGroupChoices],
-  );
-  return (
-    <TabGroupChoiceContext.Provider value={contextValue}>
-      {children}
-    </TabGroupChoiceContext.Provider>
-  );
+  const value = useContextValue();
+  return <Context.Provider value={value}>{children}</Context.Provider>;
 }
 
-export function useTabGroupChoice(): TabGroupChoiceContextValue {
-  const context = useContext(TabGroupChoiceContext);
+export function useTabGroupChoice(): ContextValue {
+  const context = useContext(Context);
   if (context == null) {
     throw new ReactContextError('TabGroupChoiceProvider');
   }