@docusaurus/theme-common 2.0.0-beta.16 → 2.0.0-beta.19

package/src/contexts/navbarSecondaryMenu/content.tsx

@@ -0,0 +1,110 @@
+/**
+ * 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,
+  type ReactNode,
+  type ComponentType,
+} from 'react';
+import {ReactContextError} from '../../utils/reactUtils';
+
+// This context represents a "global layout store". A component (usually a
+// layout component) can request filling this store through
+// `NavbarSecondaryMenuFiller`. It doesn't actually control rendering by itself,
+// and this context should be considered internal implementation. The user-
+// facing value comes from `display.tsx`, which takes the `component` and
+// `props` stored here and renders the actual element.
+
+export type NavbarSecondaryMenuComponent<Props> = ComponentType<Props>;
+
+/** @internal */
+export type Content =
+  | {
+      component: NavbarSecondaryMenuComponent<object>;
+      props: object;
+    }
+  | {component: null; props: null};
+
+type ContextValue = [
+  content: Content,
+  setContent: React.Dispatch<React.SetStateAction<Content>>,
+];
+
+const Context = React.createContext<ContextValue | null>(null);
+
+/** @internal */
+export function NavbarSecondaryMenuContentProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const value = useState({component: null, props: null});
+  return (
+    // @ts-expect-error: this context is hard to type
+    <Context.Provider value={value}>{children}</Context.Provider>
+  );
+}
+
+/** @internal */
+export function useNavbarSecondaryMenuContent(): Content {
+  const value = useContext(Context);
+  if (!value) {
+    throw new ReactContextError('NavbarSecondaryMenuContentProvider');
+  }
+  return value[0];
+}
+
+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 context = useContext(Context);
+  if (!context) {
+    throw new ReactContextError('NavbarSecondaryMenuContentProvider');
+  }
+  const [, setContent] = context;
+
+  // To avoid useless context re-renders, props are memoized shallowly
+  const memoizedProps = useShallowMemoizedObject(props);
+
+  useEffect(() => {
+    // @ts-expect-error: this context is hard to type
+    setContent({component, props: memoizedProps});
+  }, [setContent, component, memoizedProps]);
+
+  useEffect(
+    () => () => setContent({component: null, props: null}),
+    [setContent],
+  );
+
+  return null;
+}

package/src/contexts/navbarSecondaryMenu/display.tsx

@@ -0,0 +1,102 @@
+/**
+ * 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,
+} from 'react';
+import {ReactContextError, usePrevious} from '../../utils/reactUtils';
+import {useNavbarMobileSidebar} from '../navbarMobileSidebar';
+import {useNavbarSecondaryMenuContent, type Content} from './content';
+
+type ContextValue = [
+  shown: boolean,
+  setShown: React.Dispatch<React.SetStateAction<boolean>>,
+];
+
+const Context = React.createContext<ContextValue | null>(null);
+
+function useContextValue(): ContextValue {
+  const mobileSidebar = useNavbarMobileSidebar();
+  const content = useNavbarSecondaryMenuContent();
+
+  const [shown, setShown] = useState(false);
+
+  const hasContent = content.component !== null;
+  const previousHasContent = usePrevious(hasContent);
+
+  // 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 useMemo(() => [shown, setShown], [shown]);
+}
+
+/** @internal */
+export function NavbarSecondaryMenuDisplayProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const value = useContextValue();
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+function renderElement(content: Content): JSX.Element | undefined {
+  if (content.component) {
+    const Comp = content.component;
+    return <Comp {...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 value = useContext(Context);
+  if (!value) {
+    throw new ReactContextError('NavbarSecondaryMenuDisplayProvider');
+  }
+  const [shown, setShown] = value;
+  const hide = useCallback(() => setShown(false), [setShown]);
+  const content = useNavbarSecondaryMenuContent();
+
+  return useMemo(
+    () => ({shown, hide, content: renderElement(content)}),
+    [hide, content, shown],
+  );
+}

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

@@ -9,35 +9,38 @@ import React, {
   useState,
   useCallback,
   useEffect,
-  createContext,
   useMemo,
   useContext,
   type ReactNode,
 } from 'react';
-import {createStorageSlot, listStorageKeys} from './storageUtils';
+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;
   }>({});
-  const setChoiceSyncWithLocalStorage = useCallback((groupId, newChoice) => {
-    createStorageSlot(`${TAB_CHOICE_PREFIX}${groupId}`).set(newChoice);
-  }, []);
+  const setChoiceSyncWithLocalStorage = useCallback(
+    (groupId: string, newChoice: string) => {
+      createStorageSlot(`${TAB_CHOICE_PREFIX}${groupId}`).set(newChoice);
+    },
+    [],
+  );
 
   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);
@@ -50,13 +53,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({
@@ -64,27 +72,14 @@ 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 Error(
-      '"useUserPreferencesContext" is used outside of "Layout" component.',
-    );
+    throw new ReactContextError('TabGroupChoiceProvider');
   }
   return context;
 }

package/src/hooks/useBackToTopButton.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 {useRef, useState} from 'react';
+import {useScrollPosition, useSmoothScrollTo} from '../utils/scrollUtils';
+import {useLocationChange} from '../utils/useLocationChange';
+
+/** Wires the logic for the back to top button. */
+export function useBackToTopButton({
+  threshold,
+}: {
+  /**
+   * The minimum vertical scroll position, above which a scroll-up would not
+   * cause `shown` to become `true`. This is because BTT is only useful if the
+   * user is far down the page.
+   */
+  threshold: number;
+}): {
+  /**
+   * Whether the button should be displayed. We only show if the user has
+   * scrolled up and is on a vertical position greater than `threshold`.
+   */
+  shown: boolean;
+  /**
+   * A (memoized) handle for starting the scroll, which you can directly plug
+   * into the props.
+   */
+  scrollToTop: () => void;
+} {
+  const [shown, setShown] = useState(false);
+  const isFocusedAnchor = useRef(false);
+  const {startScroll, cancelScroll} = useSmoothScrollTo();
+
+  useScrollPosition(({scrollY: scrollTop}, lastPosition) => {
+    const lastScrollTop = lastPosition?.scrollY;
+    // Component is just being mounted. Not really a scroll event from the user.
+    // Ignore it.
+    if (!lastScrollTop) {
+      return;
+    }
+    if (isFocusedAnchor.current) {
+      // This scroll position change is triggered by navigating to an anchor.
+      // Ignore it.
+      isFocusedAnchor.current = false;
+    } else if (scrollTop >= lastScrollTop) {
+      // The user has scrolled down to "fight against" the animation. Cancel any
+      // animation under progress.
+      cancelScroll();
+      setShown(false);
+    } else if (scrollTop < threshold) {
+      // Scrolled to the minimum position; hide the button.
+      setShown(false);
+    } else if (
+      scrollTop + window.innerHeight <
+      document.documentElement.scrollHeight
+    ) {
+      setShown(true);
+    }
+  });
+
+  useLocationChange((locationChangeEvent) => {
+    if (locationChangeEvent.location.hash) {
+      isFocusedAnchor.current = true;
+      setShown(false);
+    }
+  });
+
+  return {shown, scrollToTop: () => startScroll(0)};
+}

package/src/hooks/useCodeWordWrap.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 {RefObject} from 'react';
+import {useState, useCallback, useEffect, useRef} from 'react';
+
+export function useCodeWordWrap(): {
+  readonly codeBlockRef: RefObject<HTMLPreElement>;
+  readonly isEnabled: boolean;
+  readonly isCodeScrollable: boolean;
+  readonly toggle: () => void;
+} {
+  const [isEnabled, setIsEnabled] = useState(false);
+  const [isCodeScrollable, setIsCodeScrollable] = useState<boolean>(false);
+  const codeBlockRef = useRef<HTMLPreElement>(null);
+
+  const toggle = useCallback(() => {
+    const codeElement = codeBlockRef.current!.querySelector('code')!;
+
+    if (isEnabled) {
+      codeElement.removeAttribute('style');
+    } else {
+      codeElement.style.whiteSpace = 'pre-wrap';
+    }
+
+    setIsEnabled((value) => !value);
+  }, [codeBlockRef, isEnabled]);
+
+  const updateCodeIsScrollable = useCallback(() => {
+    const {scrollWidth, clientWidth} = codeBlockRef.current!;
+    const isScrollable =
+      scrollWidth > clientWidth ||
+      codeBlockRef.current!.querySelector('code')!.hasAttribute('style');
+    setIsCodeScrollable(isScrollable);
+  }, [codeBlockRef]);
+
+  useEffect(() => {
+    updateCodeIsScrollable();
+  }, [isEnabled, updateCodeIsScrollable]);
+
+  useEffect(() => {
+    window.addEventListener('resize', updateCodeIsScrollable, {
+      passive: true,
+    });
+
+    return () => {
+      window.removeEventListener('resize', updateCodeIsScrollable);
+    };
+  }, [updateCodeIsScrollable]);
+
+  return {codeBlockRef, isEnabled, isCodeScrollable, toggle};
+}

package/src/hooks/useHideableNavbar.ts

@@ -9,14 +9,16 @@ import {useState, useCallback, useRef} from 'react';
 import {useLocationChange} from '../utils/useLocationChange';
 import {useScrollPosition} from '../utils/scrollUtils';
 
-type UseHideableNavbarReturns = {
+/**
+ * Wires the imperative logic of a hideable navbar.
+ * @param hideOnScroll If `false`, this hook is basically a no-op.
+ */
+export function useHideableNavbar(hideOnScroll: boolean): {
+  /** A ref to the navbar component. Plug this into the actual element. */
   readonly navbarRef: (node: HTMLElement | null) => void;
+  /** If `false`, the navbar component should not be rendered. */
   readonly isNavbarVisible: boolean;
-};
-
-export default function useHideableNavbar(
-  hideOnScroll: boolean,
-): UseHideableNavbarReturns {
+} {
   const [isNavbarVisible, setIsNavbarVisible] = useState(hideOnScroll);
   const isFocusedAnchor = useRef(false);
   const navbarHeight = useRef(0);
@@ -26,14 +28,13 @@ export default function useHideableNavbar(
     }
   }, []);
 
-  useScrollPosition((currentPosition, lastPosition) => {
+  useScrollPosition(({scrollY: scrollTop}, lastPosition) => {
     if (!hideOnScroll) {
       return;
     }
 
-    const scrollTop = currentPosition.scrollY;
-
-    // It needed for mostly to handle rubber band scrolling
+    // Needed mostly for handling rubber band scrolling.
+    // See https://github.com/facebook/docusaurus/pull/5721
     if (scrollTop < navbarHeight.current) {
       setIsNavbarVisible(true);
       return;
@@ -70,8 +71,5 @@ export default function useHideableNavbar(
     setIsNavbarVisible(true);
   });
 
-  return {
-    navbarRef,
-    isNavbarVisible,
-  };
+  return {navbarRef, isNavbarVisible};
 }

package/src/hooks/useKeyboardNavigation.ts

@@ -11,9 +11,17 @@ import './styles.css';
 
 export const keyboardFocusedClassName = 'navigation-with-keyboard';
 
-// 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 {
+/**
+ * Side-effect that adds the `keyboardFocusedClassName` to the body element when
+ * the keyboard has been pressed, or removes it when the mouse is clicked.
+ *
+ * The presence of this class name signals that the user may be using keyboard
+ * for navigation, and the theme **must** add focus outline when this class name
+ * is present. (And optionally not if it's absent, for design purposes)
+ *
+ * Inspired by https://hackernoon.com/removing-that-ugly-focus-ring-and-keeping-it-too-6c8727fefcd2
+ */
+export function useKeyboardNavigation(): void {
   useEffect(() => {
     function handleOutlineStyles(e: MouseEvent | KeyboardEvent) {
       if (e.type === 'keydown' && (e as KeyboardEvent).key === 'Tab') {

package/src/hooks/useLockBodyScroll.ts

@@ -7,10 +7,13 @@
 
 import {useEffect} from 'react';
 
-export default function useLockBodyScroll(lock: boolean = true): void {
+/**
+ * Side-effect that locks the document body's scroll throughout the lifetime of
+ * the containing component. e.g. when the mobile sidebar is expanded.
+ */
+export function useLockBodyScroll(lock: boolean = true): void {
   useEffect(() => {
     document.body.style.overflow = lock ? 'hidden' : 'visible';
-
     return () => {
       document.body.style.overflow = 'visible';
     };

package/src/hooks/usePrismTheme.ts

@@ -5,16 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import defaultTheme from 'prism-react-renderer/themes/palenight';
-import {useColorMode} from '../utils/colorModeUtils';
+import type {PrismTheme} from 'prism-react-renderer';
+import {useColorMode} from '../contexts/colorMode';
 import {useThemeConfig} from '../utils/useThemeConfig';
 
-export default function usePrismTheme(): typeof defaultTheme {
+/**
+ * Returns a color-mode-dependent Prism theme: whatever the user specified in
+ * the config. Falls back to `palenight`.
+ */
+export function usePrismTheme(): PrismTheme {
   const {prism} = useThemeConfig();
-  const {isDarkTheme} = useColorMode();
-  const lightModeTheme = prism.theme || defaultTheme;
+  const {colorMode} = useColorMode();
+  const lightModeTheme = prism.theme;
   const darkModeTheme = prism.darkTheme || lightModeTheme;
-  const prismTheme = isDarkTheme ? darkModeTheme : lightModeTheme;
+  const prismTheme = colorMode === 'dark' ? darkModeTheme : lightModeTheme;
 
   return prismTheme;
 }

package/src/hooks/useSearchPage.ts

@@ -11,13 +11,24 @@ import {useCallback, useEffect, useState} from 'react';
 
 const SEARCH_PARAM_QUERY = 'q';
 
-interface UseSearchPageReturn {
+/** Some utility functions around search queries. */
+export function useSearchPage(): {
+  /**
+   * Works hand-in-hand with `setSearchQuery`; whatever the user has inputted
+   * into the search box.
+   */
   searchQuery: string;
+  /**
+   * Set a new search query. In addition to updating `searchQuery`, this handle
+   * also mutates the location and appends the query.
+   */
   setSearchQuery: (newSearchQuery: string) => void;
+  /**
+   * Given a query, this handle generates the corresponding search page link,
+   * with base URL prepended.
+   */
   generateSearchPageLink: (targetSearchQuery: string) => string;
-}
-
-export default function useSearchPage(): UseSearchPageReturn {
+} {
   const history = useHistory();
   const {
     siteConfig: {baseUrl},
@@ -54,7 +65,9 @@ export default function useSearchPage(): UseSearchPageReturn {
   const generateSearchPageLink = useCallback(
     (targetSearchQuery: string) =>
       // Refer to https://github.com/facebook/docusaurus/pull/2838
-      `${baseUrl}search?q=${encodeURIComponent(targetSearchQuery)}`,
+      `${baseUrl}search?${SEARCH_PARAM_QUERY}=${encodeURIComponent(
+        targetSearchQuery,
+      )}`,
     [baseUrl],
   );
 

package/src/hooks/useSkipToContent.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 React from 'react';
+import {useCallback, useRef} from 'react';
+import {useHistory} from '@docusaurus/router';
+import {useLocationChange} from '../utils/useLocationChange';
+import {ThemeClassNames} from '../utils/ThemeClassNames';
+
+function programmaticFocus(el: HTMLElement) {
+  el.setAttribute('tabindex', '-1');
+  el.focus();
+  el.removeAttribute('tabindex');
+}
+
+/** This hook wires the logic for a skip-to-content link. */
+export function useSkipToContent(): {
+  /**
+   * The ref to the container. On page transition, the container will be focused
+   * so that keyboard navigators can instantly interact with the link and jump
+   * to content. **Note:** the type is `RefObject<HTMLDivElement>` only because
+   * the typing for refs don't reflect that the `ref` prop is contravariant, so
+   * using `HTMLElement` causes type-checking to fail. You can plug the ref into
+   * any HTML element, as long as it can be focused.
+   */
+  containerRef: React.RefObject<HTMLDivElement>;
+  /**
+   * Callback fired when the skip to content link has been interacted with. It
+   * will programmatically focus the main content.
+   */
+  handleSkip: (e: React.MouseEvent<HTMLAnchorElement>) => void;
+} {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const {action} = useHistory();
+  const handleSkip = useCallback((e: React.MouseEvent<HTMLAnchorElement>) => {
+    e.preventDefault();
+
+    const targetElement: HTMLElement | null =
+      document.querySelector('main:first-of-type') ||
+      document.querySelector(`.${ThemeClassNames.wrapper.main}`);
+
+    if (targetElement) {
+      programmaticFocus(targetElement);
+    }
+  }, []);
+
+  useLocationChange(({location}) => {
+    if (containerRef.current && !location.hash && action === 'PUSH') {
+      programmaticFocus(containerRef.current);
+    }
+  });
+
+  return {containerRef, handleSkip};
+}