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

package/src/contexts/navbarMobileSidebar.tsx

@@ -12,9 +12,9 @@ import React, {
   useMemo,
   type ReactNode,
 } from 'react';
+import {useNavbarSecondaryMenuContent} from './navbarSecondaryMenu/content';
 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';
 
@@ -40,9 +40,9 @@ type ContextValue = {
 const Context = React.createContext<ContextValue | undefined>(undefined);
 
 function useIsNavbarMobileSidebarDisabled() {
-  const activeDocPlugin = useActivePlugin();
+  const secondaryMenuContent = useNavbarSecondaryMenuContent();
   const {items} = useThemeConfig().navbar;
-  return items.length === 0 && !activeDocPlugin;
+  return items.length === 0 && !secondaryMenuContent.component;
 }
 
 function useContextValue(): ContextValue {
@@ -58,9 +58,9 @@ function useContextValue(): ContextValue {
   useHistoryPopHandler(() => {
     if (shown) {
       setShown(false);
-      // Should we prevent the navigation here?
+      // Prevent pop navigation; seems desirable enough
       // See https://github.com/facebook/docusaurus/pull/5462#issuecomment-911699846
-      return false; // prevent pop navigation
+      return false;
     }
     return undefined;
   });

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/contexts/tabGroupChoice.tsx

@@ -31,9 +31,12 @@ 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 {

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

@@ -28,13 +28,11 @@ export function useHideableNavbar(hideOnScroll: boolean): {
     }
   }, []);
 
-  useScrollPosition((currentPosition, lastPosition) => {
+  useScrollPosition(({scrollY: scrollTop}, lastPosition) => {
     if (!hideOnScroll) {
       return;
     }
 
-    const scrollTop = currentPosition.scrollY;
-
     // Needed mostly for handling rubber band scrolling.
     // See https://github.com/facebook/docusaurus/pull/5721
     if (scrollTop < navbarHeight.current) {

package/src/hooks/usePrismTheme.ts

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

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};
+}

package/src/hooks/useTOCHighlight.ts

@@ -81,8 +81,8 @@ function getActiveAnchor(
     // https://github.com/facebook/docusaurus/issues/5318
     return anchors[anchors.indexOf(nextVisibleAnchor) - 1] ?? null;
   }
-  // no anchor under viewport top? (ie we are at the bottom of the page)
-  // => highlight the last anchor found
+  // No anchor under viewport top (i.e. we are at the bottom of the page),
+  // highlight the last anchor found
   return anchors[anchors.length - 1] ?? null;
 }
 
@@ -140,7 +140,7 @@ export function useTOCHighlight(config: TOCHighlightConfig | undefined): void {
 
   useEffect(() => {
     if (!config) {
-      // no-op, highlighting is disabled
+      // No-op, highlighting is disabled
       return () => {};
     }
 

package/src/index.ts

@@ -34,6 +34,8 @@ export {
   parseCodeBlockTitle,
   parseLanguage,
   parseLines,
+  containsLineNumbers,
+  getPrismCssVariables,
 } from './utils/codeBlockUtils';
 
 export {
@@ -50,6 +52,10 @@ export {
   useCurrentSidebarCategory,
   isActiveSidebarItem,
   useSidebarBreadcrumbs,
+  useDocsVersionCandidates,
+  useLayoutDoc,
+  useLayoutDocsSidebar,
+  useDocRouteMetadata,
 } from './utils/docsUtils';
 
 export {useTitleFormatter} from './utils/generalUtils';
@@ -60,8 +66,6 @@ export {useLocationChange} from './utils/useLocationChange';
 
 export {useCollapsible, Collapsible} from './components/Collapsible';
 
-export {Details, type DetailsProps} from './components/Details';
-
 export {
   useDocsPreferredVersion,
   useDocsPreferredVersionByPluginId,
@@ -83,7 +87,6 @@ export {
   translateTagsPageTitle,
   listTagsByLetters,
   type TagLetterEntry,
-  type TagsListItem,
 } from './utils/tagsUtils';
 
 export {useHistoryPopHandler} from './utils/historyUtils';
@@ -106,6 +109,7 @@ export {
   useScrollController,
   useScrollPosition,
   useScrollPositionBlocker,
+  useSmoothScrollTo,
 } from './utils/scrollUtils';
 
 export {
@@ -140,11 +144,12 @@ export {
 
 export {useNavbarMobileSidebar} from './contexts/navbarMobileSidebar';
 export {
-  useNavbarSecondaryMenu,
   NavbarSecondaryMenuFiller,
   type NavbarSecondaryMenuComponent,
-} from './contexts/navbarSecondaryMenu';
+} from './contexts/navbarSecondaryMenu/content';
+export {useNavbarSecondaryMenu} from './contexts/navbarSecondaryMenu/display';
 
+export {useBackToTopButton} from './hooks/useBackToTopButton';
 export {useHideableNavbar} from './hooks/useHideableNavbar';
 export {
   useKeyboardNavigation,
@@ -154,3 +159,5 @@ export {usePrismTheme} from './hooks/usePrismTheme';
 export {useLockBodyScroll} from './hooks/useLockBodyScroll';
 export {useWindowSize} from './hooks/useWindowSize';
 export {useSearchPage} from './hooks/useSearchPage';
+export {useCodeWordWrap} from './hooks/useCodeWordWrap';
+export {useSkipToContent} from './hooks/useSkipToContent';