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

package/src/hooks/useHideableNavbar.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 {useState, useCallback, useRef} from 'react';
+import {useLocationChange} from '../utils/useLocationChange';
+import {useScrollPosition} from '../utils/scrollUtils';
+
+type UseHideableNavbarReturns = {
+  readonly navbarRef: (node: HTMLElement | null) => void;
+  readonly isNavbarVisible: boolean;
+};
+
+export default function useHideableNavbar(
+  hideOnScroll: boolean,
+): UseHideableNavbarReturns {
+  const [isNavbarVisible, setIsNavbarVisible] = useState(hideOnScroll);
+  const isFocusedAnchor = useRef(false);
+  const navbarHeight = useRef(0);
+  const navbarRef = useCallback((node: HTMLElement | null) => {
+    if (node !== null) {
+      navbarHeight.current = node.getBoundingClientRect().height;
+    }
+  }, []);
+
+  useScrollPosition((currentPosition, lastPosition) => {
+    if (!hideOnScroll) {
+      return;
+    }
+
+    const scrollTop = currentPosition.scrollY;
+
+    // It needed for mostly to handle rubber band scrolling
+    if (scrollTop < navbarHeight.current) {
+      setIsNavbarVisible(true);
+      return;
+    }
+
+    if (isFocusedAnchor.current) {
+      isFocusedAnchor.current = false;
+      return;
+    }
+
+    const lastScrollTop = lastPosition?.scrollY;
+    const documentHeight =
+      document.documentElement.scrollHeight - navbarHeight.current;
+    const windowHeight = window.innerHeight;
+
+    if (lastScrollTop && scrollTop >= lastScrollTop) {
+      setIsNavbarVisible(false);
+    } else if (scrollTop + windowHeight < documentHeight) {
+      setIsNavbarVisible(true);
+    }
+  });
+
+  useLocationChange((locationChangeEvent) => {
+    if (!hideOnScroll) {
+      return;
+    }
+
+    if (locationChangeEvent.location.hash) {
+      isFocusedAnchor.current = true;
+      setIsNavbarVisible(false);
+      return;
+    }
+
+    setIsNavbarVisible(true);
+  });
+
+  return {
+    navbarRef,
+    isNavbarVisible,
+  };
+}

package/src/hooks/useKeyboardNavigation.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 {useEffect} from 'react';
+
+import './styles.css';
+
+// This hook detect keyboard focus indicator to not show outline for mouse users
+// Inspired by https://hackernoon.com/removing-that-ugly-focus-ring-and-keeping-it-too-6c8727fefcd2
+export default function useKeyboardNavigation(): void {
+  useEffect(() => {
+    const keyboardFocusedClassName = 'navigation-with-keyboard';
+
+    function handleOutlineStyles(e: MouseEvent | KeyboardEvent) {
+      if (e.type === 'keydown' && (e as KeyboardEvent).key === 'Tab') {
+        document.body.classList.add(keyboardFocusedClassName);
+      }
+
+      if (e.type === 'mousedown') {
+        document.body.classList.remove(keyboardFocusedClassName);
+      }
+    }
+
+    document.addEventListener('keydown', handleOutlineStyles);
+    document.addEventListener('mousedown', handleOutlineStyles);
+
+    return () => {
+      document.body.classList.remove(keyboardFocusedClassName);
+      document.removeEventListener('keydown', handleOutlineStyles);
+      document.removeEventListener('mousedown', handleOutlineStyles);
+    };
+  }, []);
+}

package/src/hooks/useLockBodyScroll.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 {useEffect} from 'react';
+
+export default function useLockBodyScroll(lock: boolean = true): void {
+  useEffect(() => {
+    document.body.style.overflow = lock ? 'hidden' : 'visible';
+
+    return () => {
+      document.body.style.overflow = 'visible';
+    };
+  }, [lock]);
+}

package/src/hooks/usePrismTheme.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 defaultTheme from 'prism-react-renderer/themes/palenight';
+import {useColorMode} from '../utils/colorModeUtils';
+import {useThemeConfig} from '../utils/useThemeConfig';
+
+export default function usePrismTheme(): typeof defaultTheme {
+  const {prism} = useThemeConfig();
+  const {isDarkTheme} = useColorMode();
+  const lightModeTheme = prism.theme || defaultTheme;
+  const darkModeTheme = prism.darkTheme || lightModeTheme;
+  const prismTheme = isDarkTheme ? darkModeTheme : lightModeTheme;
+
+  return prismTheme;
+}

package/src/hooks/useSearchPage.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 {useHistory} from '@docusaurus/router';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useCallback, useEffect, useState} from 'react';
+
+const SEARCH_PARAM_QUERY = 'q';
+
+interface UseSearchPageReturn {
+  searchQuery: string;
+  setSearchQuery: (newSearchQuery: string) => void;
+  generateSearchPageLink: (targetSearchQuery: string) => string;
+}
+
+export default function useSearchPage(): UseSearchPageReturn {
+  const history = useHistory();
+  const {
+    siteConfig: {baseUrl},
+  } = useDocusaurusContext();
+
+  const [searchQuery, setSearchQueryState] = useState('');
+
+  // Init search query just after React hydration
+  useEffect(() => {
+    const searchQueryStringValue =
+      new URLSearchParams(window.location.search).get(SEARCH_PARAM_QUERY) ?? '';
+
+    setSearchQueryState(searchQueryStringValue);
+  }, []);
+
+  const setSearchQuery = useCallback(
+    (newSearchQuery: string) => {
+      const searchParams = new URLSearchParams(window.location.search);
+
+      if (newSearchQuery) {
+        searchParams.set(SEARCH_PARAM_QUERY, newSearchQuery);
+      } else {
+        searchParams.delete(SEARCH_PARAM_QUERY);
+      }
+
+      history.replace({
+        search: searchParams.toString(),
+      });
+      setSearchQueryState(newSearchQuery);
+    },
+    [history],
+  );
+
+  const generateSearchPageLink = useCallback(
+    (targetSearchQuery: string) =>
+      // Refer to https://github.com/facebook/docusaurus/pull/2838
+      `${baseUrl}search?q=${encodeURIComponent(targetSearchQuery)}`,
+    [baseUrl],
+  );
+
+  return {
+    searchQuery,
+    setSearchQuery,
+    generateSearchPageLink,
+  };
+}

package/src/hooks/useWindowSize.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 {useEffect, useState} from 'react';
+
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+const windowSizes = {
+  desktop: 'desktop',
+  mobile: 'mobile',
+
+  // This "ssr" value is very important to handle hydration FOUC / layout shifts
+  // You have to handle server-rendering explicitly on the call-site
+  // On the server, you may need to render BOTH the mobile/desktop elements (and hide one of them with mediaquery)
+  // We don't return "undefined" on purpose, to make it more explicit
+  ssr: 'ssr',
+} as const;
+
+type WindowSize = keyof typeof windowSizes;
+
+const DesktopThresholdWidth = 996;
+
+function getWindowSize() {
+  if (!ExecutionEnvironment.canUseDOM) {
+    return windowSizes.ssr;
+  }
+  return window.innerWidth > DesktopThresholdWidth
+    ? windowSizes.desktop
+    : windowSizes.mobile;
+}
+
+// Simulate the SSR window size in dev, so that potential hydration FOUC/layout shift problems can be seen in dev too!
+const DevSimulateSSR = process.env.NODE_ENV === 'development' && true;
+
+// This hook returns an enum value on purpose!
+// We don't want it to return the actual width value, for resize perf reasons
+// We only want to re-render once a breakpoint is crossed
+export default function useWindowSize(): WindowSize {
+  const [windowSize, setWindowSize] = useState<WindowSize>(() => {
+    if (DevSimulateSSR) {
+      return 'ssr';
+    }
+    return getWindowSize();
+  });
+
+  useEffect(() => {
+    function updateWindowSize() {
+      setWindowSize(getWindowSize());
+    }
+
+    const timeout = DevSimulateSSR
+      ? window.setTimeout(updateWindowSize, 1000)
+      : undefined;
+
+    window.addEventListener('resize', updateWindowSize);
+
+    return () => {
+      window.removeEventListener('resize', updateWindowSize);
+      clearTimeout(timeout);
+    };
+  }, []);
+
+  return windowSize;
+}

package/src/index.ts

@@ -6,6 +6,10 @@
  */
 
 export {useThemeConfig} from './utils/useThemeConfig';
+export {
+  DocSidebarItemsExpandedStateProvider,
+  useDocSidebarItemsExpandedState,
+} from './utils/docSidebarItemsExpandedState';
 
 export type {
   ThemeConfig,
@@ -13,8 +17,9 @@ export type {
   Navbar,
   NavbarItem,
   NavbarLogo,
+  MultiColumnFooter,
+  SimpleFooter,
   Footer,
-  FooterLinks,
   FooterLinkItem,
   ColorModeConfig,
 } from './utils/useThemeConfig';
@@ -113,3 +118,16 @@ export {
 } from './utils/reactUtils';
 
 export {isRegexpStringMatch} from './utils/regexpUtils';
+
+export {useColorMode, ColorModeProvider} from './utils/colorModeUtils';
+export {
+  useTabGroupChoice,
+  TabGroupChoiceProvider,
+} from './utils/tabGroupChoiceUtils';
+
+export {default as useHideableNavbar} from './hooks/useHideableNavbar';
+export {default as useKeyboardNavigation} from './hooks/useKeyboardNavigation';
+export {default as usePrismTheme} from './hooks/usePrismTheme';
+export {default as useLockBodyScroll} from './hooks/useLockBodyScroll';
+export {default as useWindowSize} from './hooks/useWindowSize';
+export {default as useSearchPage} from './hooks/useSearchPage';

package/src/utils/ThemeClassNames.ts

@@ -34,6 +34,7 @@ export const ThemeClassNames = {
     editThisPage: 'theme-edit-this-page',
     lastUpdated: 'theme-last-updated',
     backToTopButton: 'theme-back-to-top-button',
+    codeBlock: 'theme-code-block',
   },
   layout: {
     // TODO add other stable classNames here
@@ -47,6 +48,7 @@ export const ThemeClassNames = {
     docFooter: 'theme-doc-footer',
     docFooterTagsRow: 'theme-doc-footer-tags-row',
     docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
+    docSidebarContainer: 'theme-doc-sidebar-container',
     docSidebarMenu: 'theme-doc-sidebar-menu',
     docSidebarItemCategory: 'theme-doc-sidebar-item-category',
     docSidebarItemLink: 'theme-doc-sidebar-item-link',

package/src/utils/announcementBarUtils.tsx

@@ -10,7 +10,7 @@ import React, {
   useEffect,
   useCallback,
   useMemo,
-  ReactNode,
+  type ReactNode,
   useContext,
   createContext,
 } from 'react';
@@ -43,7 +43,7 @@ const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
 
   const [isClosed, setClosed] = useState(() =>
     isBrowser
-      ? // On client navigation: init with localstorage value
+      ? // 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,
@@ -68,6 +68,7 @@ const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
 
     // 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';
     }

package/src/utils/codeBlockUtils.ts

@@ -6,7 +6,6 @@
  */
 
 import rangeParser from 'parse-numeric-range';
-import type {Language} from 'prism-react-renderer';
 
 const codeBlockTitleRegex = /title=(["'])(.*?)\1/;
 const highlightLinesRangeRegex = /{([\d,-]+)}/;
@@ -93,11 +92,11 @@ export function parseCodeBlockTitle(metastring?: string): string {
   return metastring?.match(codeBlockTitleRegex)?.[2] ?? '';
 }
 
-export function parseLanguage(className?: string): Language | undefined {
+export function parseLanguage(className: string): string | undefined {
   const languageClassName = className
-    ?.split(' ')
+    .split(' ')
     .find((str) => str.startsWith('language-'));
-  return languageClassName?.replace(/language-/, '') as Language | undefined;
+  return languageClassName?.replace(/language-/, '');
 }
 
 /**
@@ -107,7 +106,7 @@ export function parseLanguage(className?: string): Language | undefined {
 export function parseLines(
   content: string,
   metastring?: string,
-  language?: Language,
+  language?: string,
 ): {
   highlightLines: number[];
   code: string;

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,