@docusaurus/theme-common 2.0.0-beta.14 → 2.0.0-beta.15

package/src/utils/colorModeUtils.tsx

@@ -0,0 +1,135 @@
+/**
+ * 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 type {ReactNode} from 'react';
+import React, {
+  useState,
+  useCallback,
+  useEffect,
+  useContext,
+  useMemo,
+} from 'react';
+
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import {createStorageSlot} from './storageUtils';
+import {useThemeConfig} from './useThemeConfig';
+
+type ColorModeContextValue = {
+  readonly isDarkTheme: boolean;
+  readonly setLightTheme: () => void;
+  readonly setDarkTheme: () => void;
+};
+
+const ThemeStorage = createStorageSlot('theme');
+
+const themes = {
+  light: 'light',
+  dark: 'dark',
+} as const;
+
+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 =>
+  theme === themes.dark ? themes.dark : themes.light;
+
+const getInitialTheme = (defaultMode: Themes | undefined): Themes => {
+  if (!ExecutionEnvironment.canUseDOM) {
+    return coerceToTheme(defaultMode);
+  }
+  return coerceToTheme(document.documentElement.getAttribute('data-theme'));
+};
+
+const storeTheme = (newTheme: Themes) => {
+  createStorageSlot('theme').set(coerceToTheme(newTheme));
+};
+
+function useColorModeContextValue(): ColorModeContextValue {
+  const {
+    colorMode: {defaultMode, disableSwitch, respectPrefersColorScheme},
+  } = useThemeConfig();
+  const [theme, setTheme] = useState(getInitialTheme(defaultMode));
+
+  const setLightTheme = useCallback(() => {
+    setTheme(themes.light);
+    storeTheme(themes.light);
+  }, []);
+  const setDarkTheme = useCallback(() => {
+    setTheme(themes.dark);
+    storeTheme(themes.dark);
+  }, []);
+
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', coerceToTheme(theme));
+  }, [theme]);
+
+  useEffect(() => {
+    if (disableSwitch) {
+      return;
+    }
+
+    try {
+      const storedTheme = ThemeStorage.get();
+      if (storedTheme !== null) {
+        setTheme(coerceToTheme(storedTheme));
+      }
+    } catch (err) {
+      console.error(err);
+    }
+  }, [disableSwitch, setTheme]);
+
+  useEffect(() => {
+    if (disableSwitch && !respectPrefersColorScheme) {
+      return;
+    }
+
+    window
+      .matchMedia('(prefers-color-scheme: dark)')
+      .addListener(({matches}) => {
+        setTheme(matches ? themes.dark : themes.light);
+      });
+  }, [disableSwitch, respectPrefersColorScheme]);
+
+  return {
+    isDarkTheme: theme === themes.dark,
+    setLightTheme,
+    setDarkTheme,
+  };
+}
+
+const ColorModeContext = React.createContext<ColorModeContextValue | undefined>(
+  undefined,
+);
+
+export function ColorModeProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const {isDarkTheme, setLightTheme, setDarkTheme} = useColorModeContextValue();
+  const contextValue = useMemo(
+    () => ({isDarkTheme, setLightTheme, setDarkTheme}),
+    [isDarkTheme, setLightTheme, setDarkTheme],
+  );
+  return (
+    <ColorModeContext.Provider value={contextValue}>
+      {children}
+    </ColorModeContext.Provider>
+  );
+}
+
+export function useColorMode(): ColorModeContextValue {
+  const context = useContext<ColorModeContextValue | undefined>(
+    ColorModeContext,
+  );
+  if (context == null) {
+    throw new Error(
+      '"useColorMode()" is used outside of "Layout" component. Please see https://docusaurus.io/docs/api/themes/configuration#use-color-mode.',
+    );
+  }
+  return context;
+}

package/src/utils/docSidebarItemsExpandedState.tsx

@@ -0,0 +1,41 @@
+/**
+ * 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';
+
+const EmptyContext: unique symbol = Symbol('EmptyContext');
+const Context = React.createContext<
+  DocSidebarItemsExpandedState | typeof EmptyContext
+>(EmptyContext);
+type DocSidebarItemsExpandedState = {
+  expandedItem: number | null;
+  setExpandedItem: (a: number | null) => void;
+};
+
+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(): DocSidebarItemsExpandedState {
+  const contextValue = useContext(Context);
+  if (contextValue === EmptyContext) {
+    throw new Error(
+      'This hook requires usage of <DocSidebarItemsExpandedStateProvider>',
+    );
+  }
+  return contextValue;
+}

package/src/utils/docsPreferredVersion/DocsPreferredVersionProvider.tsx

@@ -7,16 +7,19 @@
 
 import React, {
   createContext,
-  ReactNode,
+  type ReactNode,
   useContext,
   useEffect,
   useMemo,
   useState,
 } from 'react';
-import {useThemeConfig, DocsVersionPersistence} from '../useThemeConfig';
+import {useThemeConfig, type DocsVersionPersistence} from '../useThemeConfig';
 import {isDocsPluginEnabled} from '../docsUtils';
 
-import {useAllDocsData, GlobalPluginData} from '@theme/hooks/useDocs';
+import {
+  useAllDocsData,
+  type GlobalPluginData,
+} from '@docusaurus/plugin-content-docs/client';
 
 import DocsPreferredVersionStorage from './DocsPreferredVersionStorage';
 
@@ -35,7 +38,7 @@ type DocsPreferredVersionState = Record<
   DocsPreferredVersionPluginState
 >;
 
-// Initial state is always null as we can't read localstorage from node SSR
+// Initial state is always null as we can't read local storage from node SSR
 function getInitialState(pluginIds: string[]): DocsPreferredVersionState {
   const initialState: DocsPreferredVersionState = {};
   pluginIds.forEach((pluginId) => {

package/src/utils/docsPreferredVersion/DocsPreferredVersionStorage.ts

@@ -6,7 +6,7 @@
  */
 
 import {createStorageSlot} from '../storageUtils';
-import {DocsVersionPersistence} from '../useThemeConfig';
+import type {DocsVersionPersistence} from '../useThemeConfig';
 
 const storageKey = (pluginId: string) => `docs-preferred-version-${pluginId}`;
 

package/src/utils/docsPreferredVersion/useDocsPreferredVersion.ts

@@ -7,7 +7,11 @@
 
 import {useCallback} from 'react';
 import {useDocsPreferredVersionContext} from './DocsPreferredVersionProvider';
-import {useAllDocsData, useDocsData, GlobalVersion} from '@theme/hooks/useDocs';
+import {
+  useAllDocsData,
+  useDocsData,
+  type GlobalVersion,
+} from '@docusaurus/plugin-content-docs/client';
 
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
 

package/src/utils/docsUtils.tsx

@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {createContext, ReactNode, useContext} from 'react';
-import {useAllDocsData} from '@theme/hooks/useDocs';
-import {
+import React, {createContext, type ReactNode, useContext} from 'react';
+import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
+import type {
   PropSidebar,
   PropSidebarItem,
   PropSidebarItemCategory,

package/src/utils/mobileSecondaryMenu.tsx

@@ -7,11 +7,11 @@
 
 import React, {
   useState,
-  ReactNode,
+  type ReactNode,
   useContext,
   createContext,
   useEffect,
-  ComponentType,
+  type ComponentType,
   useMemo,
 } from 'react';
 
@@ -104,7 +104,7 @@ export function MobileSecondaryMenuFiller<
   const memoizedProps = useShallowMemoizedObject(props);
 
   useEffect(() => {
-    // @ts-expect-error: context is not 100% typesafe but it's ok
+    // @ts-expect-error: context is not 100% type-safe but it's ok
     setState({component, props: memoizedProps});
   }, [setState, component, memoizedProps]);
 

package/src/utils/regexpUtils.ts

@@ -6,7 +6,7 @@
  */
 
 /**
- * Utility to convert an optional string into a Regex case sensitive and global
+ * Utility to convert an optional string into a Regex case insensitive and global
  */
 export function isRegexpStringMatch(
   regexAsString?: string,

package/src/utils/scrollUtils.tsx

@@ -7,7 +7,7 @@
 
 import React, {
   createContext,
-  ReactNode,
+  type ReactNode,
   useCallback,
   useContext,
   useEffect,

package/src/utils/tabGroupChoiceUtils.tsx

@@ -0,0 +1,90 @@
+/**
+ * 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,
+  createContext,
+  useMemo,
+  useContext,
+  type ReactNode,
+} from 'react';
+import {createStorageSlot, listStorageKeys} from './storageUtils';
+
+const TAB_CHOICE_PREFIX = 'docusaurus.tab.';
+
+type TabGroupChoiceContextValue = {
+  readonly tabGroupChoices: {readonly [groupId: string]: string};
+  readonly setTabGroupChoices: (groupId: string, newChoice: string) => void;
+};
+
+const TabGroupChoiceContext = createContext<
+  TabGroupChoiceContextValue | undefined
+>(undefined);
+
+function useTabGroupChoiceContextValue(): TabGroupChoiceContextValue {
+  const [tabGroupChoices, setChoices] = useState<{
+    readonly [groupId: string]: string;
+  }>({});
+  const setChoiceSyncWithLocalStorage = useCallback((groupId, newChoice) => {
+    createStorageSlot(`${TAB_CHOICE_PREFIX}${groupId}`).set(newChoice);
+  }, []);
+
+  useEffect(() => {
+    try {
+      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()!;
+        }
+      });
+      setChoices(localStorageChoices);
+    } catch (err) {
+      console.error(err);
+    }
+  }, []);
+
+  return {
+    tabGroupChoices,
+    setTabGroupChoices: (groupId: string, newChoice: string) => {
+      setChoices((oldChoices) => ({...oldChoices, [groupId]: newChoice}));
+      setChoiceSyncWithLocalStorage(groupId, newChoice);
+    },
+  };
+}
+
+export function TabGroupChoiceProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const {tabGroupChoices, setTabGroupChoices} = useTabGroupChoiceContextValue();
+  const contextValue = useMemo(
+    () => ({
+      tabGroupChoices,
+      setTabGroupChoices,
+    }),
+    [tabGroupChoices, setTabGroupChoices],
+  );
+  return (
+    <TabGroupChoiceContext.Provider value={contextValue}>
+      {children}
+    </TabGroupChoiceContext.Provider>
+  );
+}
+
+export function useTabGroupChoice(): TabGroupChoiceContextValue {
+  const context = useContext(TabGroupChoiceContext);
+  if (context == null) {
+    throw new Error(
+      '"useUserPreferencesContext" is used outside of "Layout" component.',
+    );
+  }
+  return context;
+}

package/src/utils/tocUtils.ts

@@ -6,7 +6,7 @@
  */
 
 import {useMemo} from 'react';
-import {TOCItem} from '@docusaurus/types';
+import type {TOCItem} from '@docusaurus/types';
 
 type FilterTOCParam = {
   toc: readonly TOCItem[];

package/src/utils/useContextualSearchFilters.ts

@@ -5,7 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useAllDocsData, useActivePluginAndVersion} from '@theme/hooks/useDocs';
+import {
+  useAllDocsData,
+  useActivePluginAndVersion,
+} from '@docusaurus/plugin-content-docs/client';
 import {useDocsPreferredVersionByPluginId} from './docsPreferredVersion/useDocsPreferredVersion';
 import {docVersionSearchTag, DEFAULT_SEARCH_TAG} from './searchUtils';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

package/src/utils/useLocationChange.ts

@@ -7,7 +7,7 @@
 
 import {useEffect} from 'react';
 import {useLocation} from '@docusaurus/router';
-import {Location} from '@docusaurus/history';
+import type {Location} from '@docusaurus/history';
 import {usePrevious} from './usePrevious';
 import {useDynamicCallback} from './reactUtils';
 

package/src/utils/useTOCHighlight.ts

@@ -144,6 +144,7 @@ function useTOCHighlight(config: TOCHighlightConfig | undefined): void {
         }
         link.classList.add(linkActiveClassName);
         lastActiveLinkRef.current = link;
+        link.scrollIntoView({block: 'nearest'});
       } else {
         link.classList.remove(linkActiveClassName);
       }

package/src/utils/useThemeConfig.ts

@@ -6,9 +6,9 @@
  */
 
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {PrismTheme} from 'prism-react-renderer';
-import {CSSProperties} from 'react';
-import {DeepPartial} from 'utility-types';
+import type {PrismTheme} from 'prism-react-renderer';
+import type {CSSProperties} from 'react';
+import type {DeepPartial} from 'utility-types';
 
 export type DocsVersionPersistence = 'localStorage' | 'none';
 
@@ -122,6 +122,7 @@ export type ThemeConfig = {
   prism: PrismConfig;
   footer?: Footer;
   hideableSidebar: boolean;
+  autoCollapseSidebarCategories: boolean;
   image?: string;
   metadata: Array<Record<string, string>>;
   sidebarCollapsible: boolean;