@docusaurus/theme-common 2.0.0-beta.ff31de0ff → 2.0.1

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 {useNavbarSecondaryMenuContent} from './navbarSecondaryMenu/content';
+import {useWindowSize} from '../hooks/useWindowSize';
+import {useHistoryPopHandler} from '../utils/historyUtils';
+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 secondaryMenuContent = useNavbarSecondaryMenuContent();
+  const {items} = useThemeConfig().navbar;
+  return items.length === 0 && !secondaryMenuContent.component;
+}
+
+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);
+      // Prevent pop navigation; seems desirable enough
+      // See https://github.com/facebook/docusaurus/pull/5462#issuecomment-911699846
+      return false;
+    }
+    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/content.tsx

@@ -0,0 +1,100 @@
+/**
+ * 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,
+  type ReactNode,
+  type ComponentType,
+} from 'react';
+import {ReactContextError, useShallowMemoObject} 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];
+}
+
+/**
+ * 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 = useShallowMemoObject(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

@@ -0,0 +1,85 @@
+/**
+ * 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,
+  useMemo,
+  useContext,
+  type ReactNode,
+} from 'react';
+import {createStorageSlot, listStorageKeys} from '../utils/storageUtils';
+import {ReactContextError} from '../utils/reactUtils';
+
+const TAB_CHOICE_PREFIX = 'docusaurus.tab.';
+
+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 Context = React.createContext<ContextValue | undefined>(undefined);
+
+function useContextValue(): ContextValue {
+  const [tabGroupChoices, setChoices] = useState<{
+    readonly [groupId: string]: string;
+  }>({});
+  const setChoiceSyncWithLocalStorage = useCallback(
+    (groupId: string, newChoice: string) => {
+      createStorageSlot(`${TAB_CHOICE_PREFIX}${groupId}`).set(newChoice);
+    },
+    [],
+  );
+
+  useEffect(() => {
+    try {
+      const localStorageChoices: {[groupId: 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);
+    }
+  }, []);
+
+  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({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const value = useContextValue();
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+export function useTabGroupChoice(): ContextValue {
+  const context = useContext(Context);
+  if (context == null) {
+    throw new ReactContextError('TabGroupChoiceProvider');
+  }
+  return context;
+}

package/{lib/utils/pathUtils.d.ts → src/hooks/styles.css}

@@ -4,4 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export declare const isSamePath: (path1: string | undefined, path2: string | undefined) => boolean;
+
+body:not(.navigation-with-keyboard) *:not(input):focus {
+  outline: none;
+}

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,105 @@
+/**
+ * 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';
+import {useMutationObserver} from './useMutationObserver';
+
+// Callback fires when the "hidden" attribute of a tabpanel changes
+// See https://github.com/facebook/docusaurus/pull/7485
+function useTabBecameVisibleCallback(
+  codeBlockRef: RefObject<HTMLPreElement>,
+  callback: () => void,
+) {
+  const [hiddenTabElement, setHiddenTabElement] = useState<
+    Element | null | undefined
+  >();
+
+  const updateHiddenTabElement = useCallback(() => {
+    // No need to observe non-hidden tabs
+    // + we want to force a re-render when a tab becomes visible
+    setHiddenTabElement(
+      codeBlockRef.current?.closest('[role=tabpanel][hidden]'),
+    );
+  }, [codeBlockRef, setHiddenTabElement]);
+
+  useEffect(() => {
+    updateHiddenTabElement();
+  }, [updateHiddenTabElement]);
+
+  useMutationObserver(
+    hiddenTabElement,
+    (mutations: MutationRecord[]) => {
+      mutations.forEach((mutation) => {
+        if (
+          mutation.type === 'attributes' &&
+          mutation.attributeName === 'hidden'
+        ) {
+          callback();
+          updateHiddenTabElement();
+        }
+      });
+    },
+    {
+      attributes: true,
+      characterData: false,
+      childList: false,
+      subtree: false,
+    },
+  );
+}
+
+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';
+      // When code wrap is enabled, we want to avoid a scrollbar in any case
+      // Ensure that very very long words/strings/tokens still wrap
+      codeElement.style.overflowWrap = 'anywhere';
+    }
+
+    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]);
+
+  useTabBecameVisibleCallback(codeBlockRef, updateCodeIsScrollable);
+
+  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

@@ -0,0 +1,75 @@
+/**
+ * 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';
+
+/**
+ * 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;
+} {
+  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(({scrollY: scrollTop}, lastPosition) => {
+    if (!hideOnScroll) {
+      return;
+    }
+
+    // Needed mostly for handling rubber band scrolling.
+    // See https://github.com/facebook/docusaurus/pull/5721
+    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,45 @@
+/**
+ * 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';
+
+export const keyboardFocusedClassName = 'navigation-with-keyboard';
+
+/**
+ * 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') {
+        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);
+    };
+  }, []);
+}