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

package/src/utils/reactUtils.tsx

@@ -6,25 +6,29 @@
  */
 
 import {useCallback, useEffect, useLayoutEffect, useRef} from 'react';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 
 /**
- * This hook is like useLayoutEffect, but without the SSR warning
- * It seems hacky but it's used in many React libs (Redux, Formik...)
+ * This hook is like `useLayoutEffect`, but without the SSR warning.
+ * It seems hacky but it's used in many React libs (Redux, Formik...).
  * Also mentioned here: https://github.com/facebook/react/issues/16956
+ *
  * It is useful when you need to update a ref as soon as possible after a React
- * render (before `useEffect`)
+ * render (before `useEffect`).
  */
-export const useIsomorphicLayoutEffect =
-  typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+export const useIsomorphicLayoutEffect = ExecutionEnvironment.canUseDOM
+  ? useLayoutEffect
+  : useEffect;
 
 /**
  * Permits to transform an unstable callback (like an arrow function provided as
- * props) to a "stable" callback that is safe to use in a useEffect dependency
+ * props) to a "stable" callback that is safe to use in a `useEffect` dependency
  * array. Useful to avoid React stale closure problems + avoid useless effect
- * re-executions
+ * re-executions.
  *
  * Workaround until the React team recommends a good solution, see
  * https://github.com/facebook/react/issues/16956
+ *
  * This generally works but has some potential drawbacks, such as
  * https://github.com/facebook/react/issues/16956#issuecomment-536636418
  */
@@ -41,3 +45,32 @@ export function useDynamicCallback<T extends (...args: never[]) => unknown>(
   // but good enough for our use
   return useCallback<T>((...args) => ref.current(...args), []);
 }
+
+/**
+ * Gets `value` from the last render.
+ */
+export function usePrevious<T>(value: T): T | undefined {
+  const ref = useRef<T>();
+
+  useIsomorphicLayoutEffect(() => {
+    ref.current = value;
+  });
+
+  return ref.current;
+}
+
+/**
+ * This error is thrown when a context is consumed outside its provider. Allows
+ * reusing a generic error message format and reduces bundle size. The hook's
+ * name will be extracted from its stack, so only the provider's name is needed.
+ */
+export class ReactContextError extends Error {
+  constructor(providerName: string, additionalInfo?: string) {
+    super();
+    this.name = 'ReactContextError';
+    this.message = `Hook ${
+      this.stack?.split('\n')[1]?.match(/at (?:\w+\.)?(?<name>\w+)/)?.groups!
+        .name
+    } is called outside the <${providerName}>. ${additionalInfo || ''}`;
+  }
+}

package/src/utils/regexpUtils.ts

@@ -6,7 +6,8 @@
  */
 
 /**
- * Converts an optional string into a Regex case insensitive and global
+ * Matches a string regex (as provided from the config) against a target in a
+ * null-safe fashion, case insensitive and global.
  */
 export function isRegexpStringMatch(
   regexAsString?: string,

package/src/utils/routesUtils.ts

@@ -5,35 +5,71 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import GeneratedRoutes, {type Route} from '@generated/routes';
 import {useMemo} from 'react';
+import generatedRoutes from '@generated/routes';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import type {RouteConfig} from 'react-router-config';
 
-function isHomePageRoute(route: Route): boolean {
-  return route.path === '/' && route.exact === true;
+/**
+ * Compare the 2 paths, case insensitive and ignoring trailing slash
+ */
+export function isSamePath(
+  path1: string | undefined,
+  path2: string | undefined,
+): boolean {
+  const normalize = (pathname: string | undefined) =>
+    (!pathname || pathname?.endsWith('/')
+      ? pathname
+      : `${pathname}/`
+    )?.toLowerCase();
+  return normalize(path1) === normalize(path2);
 }
 
-function isHomeParentRoute(route: Route): boolean {
-  return route.path === '/' && route.exact === false;
-}
+/**
+ * Note that sites don't always have a homepage in practice, so we can't assume
+ * that linking to '/' is always safe.
+ * @see https://github.com/facebook/docusaurus/pull/6517#issuecomment-1048709116
+ */
+export function findHomePageRoute({
+  baseUrl,
+  routes: initialRoutes,
+}: {
+  routes: RouteConfig[];
+  baseUrl: string;
+}): RouteConfig | undefined {
+  function isHomePageRoute(route: RouteConfig): boolean {
+    return route.path === baseUrl && route.exact === true;
+  }
 
-// Note that all sites don't always have a homepage in practice
-// See https://github.com/facebook/docusaurus/pull/6517#issuecomment-1048709116
-export function findHomePageRoute(
-  routes: Route[] = GeneratedRoutes,
-): Route | undefined {
-  if (routes.length === 0) {
-    return undefined;
+  function isHomeParentRoute(route: RouteConfig): boolean {
+    return route.path === baseUrl && !route.exact;
   }
-  const homePage = routes.find(isHomePageRoute);
-  if (homePage) {
-    return homePage;
+
+  function doFindHomePageRoute(routes: RouteConfig[]): RouteConfig | undefined {
+    if (routes.length === 0) {
+      return undefined;
+    }
+    const homePage = routes.find(isHomePageRoute);
+    if (homePage) {
+      return homePage;
+    }
+    const indexSubRoutes = routes
+      .filter(isHomeParentRoute)
+      .flatMap((route) => route.routes ?? []);
+    return doFindHomePageRoute(indexSubRoutes);
   }
-  const indexSubRoutes = routes
-    .filter(isHomeParentRoute)
-    .flatMap((route) => route.routes ?? []);
-  return findHomePageRoute(indexSubRoutes);
+
+  return doFindHomePageRoute(initialRoutes);
 }
 
-export function useHomePageRoute(): Route | undefined {
-  return useMemo(() => findHomePageRoute(), []);
+/**
+ * Fetches the route that points to "/". Use this instead of the naive "/",
+ * because the homepage may not exist.
+ */
+export function useHomePageRoute(): RouteConfig | undefined {
+  const {baseUrl} = useDocusaurusContext().siteConfig;
+  return useMemo(
+    () => findHomePageRoute({routes: generatedRoutes, baseUrl}),
+    [baseUrl],
+  );
 }

package/src/utils/scrollUtils.tsx

@@ -6,37 +6,24 @@
  */
 
 import React, {
-  createContext,
-  type ReactNode,
   useCallback,
   useContext,
   useEffect,
   useLayoutEffect,
   useMemo,
   useRef,
+  type ReactNode,
 } from 'react';
-import {useDynamicCallback} from './reactUtils';
+import {useDynamicCallback, ReactContextError} from './reactUtils';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 
-/**
- * We need a way to update the scroll position while ignoring scroll events
- * without affecting Navbar/BackToTop visibility
- *
- * This API permits to temporarily disable/ignore scroll events
- * Motivated by https://github.com/facebook/docusaurus/pull/5618
- */
 type ScrollController = {
-  /**
-   * A boolean ref tracking whether scroll events are enabled
-   */
+  /** A boolean ref tracking whether scroll events are enabled. */
   scrollEventsEnabledRef: React.MutableRefObject<boolean>;
-  /**
-   * Enables scroll events in `useScrollPosition`
-   */
+  /** Enable scroll events in `useScrollPosition`. */
   enableScrollEvents: () => void;
-  /**
-   * Disables scroll events in `useScrollPosition`
-   */
+  /** Disable scroll events in `useScrollPosition`. */
   disableScrollEvents: () => void;
 };
 
@@ -57,7 +44,7 @@ function useScrollControllerContextValue(): ScrollController {
   );
 }
 
-const ScrollMonitorContext = createContext<ScrollController | undefined>(
+const ScrollMonitorContext = React.createContext<ScrollController | undefined>(
   undefined,
 );
 
@@ -66,23 +53,31 @@ export function ScrollControllerProvider({
 }: {
   children: ReactNode;
 }): JSX.Element {
+  const value = useScrollControllerContextValue();
   return (
-    <ScrollMonitorContext.Provider value={useScrollControllerContextValue()}>
+    <ScrollMonitorContext.Provider value={value}>
       {children}
     </ScrollMonitorContext.Provider>
   );
 }
 
+/**
+ * We need a way to update the scroll position while ignoring scroll events
+ * so as not to toggle Navbar/BackToTop visibility.
+ *
+ * This API permits to temporarily disable/ignore scroll events. Motivated by
+ * https://github.com/facebook/docusaurus/pull/5618
+ */
 export function useScrollController(): ScrollController {
   const context = useContext(ScrollMonitorContext);
   if (context == null) {
-    throw new Error(
-      '"useScrollController" is used but no context provider was found in the React tree.',
-    );
+    throw new ReactContextError('ScrollControllerProvider');
   }
   return context;
 }
 
+type ScrollPosition = {scrollX: number; scrollY: number};
+
 const getScrollPosition = (): ScrollPosition | null =>
   ExecutionEnvironment.canUseDOM
     ? {
@@ -91,8 +86,14 @@ const getScrollPosition = (): ScrollPosition | null =>
       }
     : null;
 
-type ScrollPosition = {scrollX: number; scrollY: number};
-
+/**
+ * This hook fires an effect when the scroll position changes. The effect will
+ * be provided with the before/after scroll positions. Note that the effect may
+ * not be always run: if scrolling is disabled through `useScrollController`, it
+ * will be a no-op.
+ *
+ * @see {@link useScrollController}
+ */
 export function useScrollPosition(
   effect: (
     position: ScrollPosition,
@@ -127,22 +128,16 @@ export function useScrollPosition(
     window.addEventListener('scroll', handleScroll, opts);
 
     return () => window.removeEventListener('scroll', handleScroll, opts);
-  }, [
-    dynamicEffect,
-    scrollEventsEnabledRef,
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    ...deps,
-  ]);
+  }, [dynamicEffect, scrollEventsEnabledRef, ...deps]);
 }
 
 type UseScrollPositionSaver = {
-  /**
-   * Measure the top of an element, and store the details
-   */
+  /** Measure the top of an element, and store the details. */
   save: (elem: HTMLElement) => void;
   /**
    * Restore the page position to keep the stored element's position from
-   * the top of the viewport, and remove the stored details
+   * the top of the viewport, and remove the stored details.
    */
   restore: () => {restored: boolean};
 };
@@ -180,21 +175,24 @@ function useScrollPositionSaver(): UseScrollPositionSaver {
   return useMemo(() => ({save, restore}), [restore, save]);
 }
 
-type UseScrollPositionBlockerReturn = {
-  blockElementScrollPositionUntilNextRender: (el: HTMLElement) => void;
-};
-
 /**
- * This hook permits to "block" the scroll position of a dom element
+ * This hook permits to "block" the scroll position of a DOM element.
  * The idea is that we should be able to update DOM content above this element
- * but the screen position of this element should not change
+ * but the screen position of this element should not change.
+ *
+ * Feature motivated by the Tabs groups: clicking on a tab may affect tabs of
+ * the same group upper in the tree, yet to avoid a bad UX, the clicked tab must
+ * remain under the user mouse.
  *
- * Feature motivated by the Tabs groups:
- * clicking on a tab may affect tabs of the same group upper in the tree
- * Yet to avoid a bad UX, the clicked tab must remain under the user mouse!
- * See GIF here: https://github.com/facebook/docusaurus/pull/5618
+ * @see https://github.com/facebook/docusaurus/pull/5618
  */
-export function useScrollPositionBlocker(): UseScrollPositionBlockerReturn {
+export function useScrollPositionBlocker(): {
+  /**
+   * Takes an element, and keeps its screen position no matter what's getting
+   * rendered above it, until the next render.
+   */
+  blockElementScrollPositionUntilNextRender: (el: HTMLElement) => void;
+} {
   const scrollController = useScrollController();
   const scrollPositionSaver = useScrollPositionSaver();
 
@@ -210,9 +208,9 @@ export function useScrollPositionBlocker(): UseScrollPositionBlockerReturn {
         const {restored} = scrollPositionSaver.restore();
         nextLayoutEffectCallbackRef.current = undefined;
 
-        // Restoring the former scroll position will trigger a scroll event
-        // We need to wait for next scroll event to happen
-        // before enabling again the scrollController events
+        // Restoring the former scroll position will trigger a scroll event. We
+        // need to wait for next scroll event to happen before enabling the
+        // scrollController events again.
         if (restored) {
           const handleScrollRestoreEvent = () => {
             scrollController.enableScrollEvents();
@@ -235,3 +233,76 @@ export function useScrollPositionBlocker(): UseScrollPositionBlockerReturn {
     blockElementScrollPositionUntilNextRender,
   };
 }
+
+type CancelScrollTop = () => void;
+
+function smoothScrollNative(top: number): CancelScrollTop {
+  window.scrollTo({top, behavior: 'smooth'});
+  return () => {
+    // Nothing to cancel, it's natively cancelled if user tries to scroll down
+  };
+}
+
+function smoothScrollPolyfill(top: number): CancelScrollTop {
+  let raf: number | null = null;
+  const isUpScroll = document.documentElement.scrollTop > top;
+  function rafRecursion() {
+    const currentScroll = document.documentElement.scrollTop;
+    if (
+      (isUpScroll && currentScroll > top) ||
+      (!isUpScroll && currentScroll < top)
+    ) {
+      raf = requestAnimationFrame(rafRecursion);
+      window.scrollTo(0, Math.floor((currentScroll - top) * 0.85) + top);
+    }
+  }
+  rafRecursion();
+
+  // Break the recursion. Prevents the user from "fighting" against that
+  // recursion producing a weird UX
+  return () => raf && cancelAnimationFrame(raf);
+}
+
+/**
+ * A "smart polyfill" of `window.scrollTo({ top, behavior: "smooth" })`.
+ * This currently always uses a polyfilled implementation unless
+ * `scroll-behavior: smooth` has been set in CSS, because native support
+ * detection for scroll behavior seems unreliable.
+ *
+ * This hook does not do anything by itself: it returns a start and a stop
+ * handle. You can execute either handle at any time.
+ */
+export function useSmoothScrollTo(): {
+  /**
+   * Start the scroll.
+   *
+   * @param top The final scroll top position.
+   */
+  startScroll: (top: number) => void;
+  /**
+   * A cancel function, because the non-native smooth scroll-top
+   * implementation must be interrupted if user scrolls down. If there's no
+   * existing animation or the scroll is using native behavior, this is a no-op.
+   */
+  cancelScroll: CancelScrollTop;
+} {
+  const cancelRef = useRef<CancelScrollTop | null>(null);
+  const isBrowser = useIsBrowser();
+  // Not all have support for smooth scrolling (particularly Safari mobile iOS)
+  // TODO proper detection is currently unreliable!
+  // see https://github.com/wessberg/scroll-behavior-polyfill/issues/16
+  // For now, we only use native scroll behavior if smooth is already set,
+  // because otherwise the polyfill produces a weird UX when both CSS and JS try
+  // to scroll a page, and they cancel each other.
+  const supportsNativeSmoothScrolling =
+    isBrowser &&
+    getComputedStyle(document.documentElement).scrollBehavior === 'smooth';
+  return {
+    startScroll: (top: number) => {
+      cancelRef.current = supportsNativeSmoothScrolling
+        ? smoothScrollNative(top)
+        : smoothScrollPolyfill(top);
+    },
+    cancelScroll: () => cancelRef.current?.(),
+  };
+}

package/src/utils/searchUtils.ts

@@ -5,11 +5,62 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {
+  useAllDocsData,
+  useActivePluginAndVersion,
+} from '@docusaurus/plugin-content-docs/client';
+import {useDocsPreferredVersionByPluginId} from '../contexts/docsPreferredVersion';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
 export const DEFAULT_SEARCH_TAG = 'default';
 
+/** The search tag to append as each doc's metadata. */
 export function docVersionSearchTag(
   pluginId: string,
   versionName: string,
 ): string {
   return `docs-${pluginId}-${versionName}`;
 }
+
+/**
+ * Gets the relevant context information for contextual search.
+ *
+ * The value is generic and not coupled to Algolia/DocSearch, since we may want
+ * to support multiple search engines, or allowing users to use their own search
+ * engine solution.
+ */
+export function useContextualSearchFilters(): {locale: string; tags: string[]} {
+  const {i18n} = useDocusaurusContext();
+  const allDocsData = useAllDocsData();
+  const activePluginAndVersion = useActivePluginAndVersion();
+  const docsPreferredVersionByPluginId = useDocsPreferredVersionByPluginId();
+
+  // This can't use more specialized hooks because we are mapping over all
+  // plugin instances.
+  function getDocPluginTags(pluginId: string) {
+    const activeVersion =
+      activePluginAndVersion?.activePlugin?.pluginId === pluginId
+        ? activePluginAndVersion.activeVersion
+        : undefined;
+
+    const preferredVersion = docsPreferredVersionByPluginId[pluginId];
+
+    const latestVersion = allDocsData[pluginId]!.versions.find(
+      (v) => v.isLast,
+    )!;
+
+    const version = activeVersion ?? preferredVersion ?? latestVersion;
+
+    return docVersionSearchTag(pluginId, version.name);
+  }
+
+  const tags = [
+    DEFAULT_SEARCH_TAG,
+    ...Object.keys(allDocsData).map(getDocPluginTags),
+  ];
+
+  return {
+    locale: i18n.currentLocale,
+    tags,
+  };
+}

package/src/utils/storageUtils.ts

@@ -11,8 +11,12 @@ export type StorageType = typeof StorageTypes[number];
 
 const DefaultStorageType: StorageType = 'localStorage';
 
-// Will return null browser storage is unavailable (like running Docusaurus in
-// iframe) See https://github.com/facebook/docusaurus/pull/4501
+/**
+ * Will return `null` if browser storage is unavailable (like running Docusaurus
+ * in an iframe). This should NOT be called in SSR.
+ *
+ * @see https://github.com/facebook/docusaurus/pull/4501
+ */
 function getBrowserStorage(
   storageType: StorageType = DefaultStorageType,
 ): Storage | null {
@@ -32,11 +36,12 @@ function getBrowserStorage(
   }
 }
 
+let hasLoggedBrowserStorageNotAvailableWarning = false;
 /**
- * Poor man's memoization to avoid logging multiple times the same warning
- * Sometimes, localStorage/sessionStorage is unavailable due to browser policies
+ * Poor man's memoization to avoid logging multiple times the same warning.
+ * Sometimes, `localStorage`/`sessionStorage` is unavailable due to browser
+ * policies.
  */
-let hasLoggedBrowserStorageNotAvailableWarning = false;
 function logOnceBrowserStorageNotAvailableWarning(error: Error) {
   if (!hasLoggedBrowserStorageNotAvailableWarning) {
     console.warn(
@@ -49,11 +54,11 @@ Possible reasons: running Docusaurus in an iframe, in an incognito browser sessi
 }
 
 // Convenient storage interface for a single storage key
-export interface StorageSlot {
+export type StorageSlot = {
   get: () => string | null;
   set: (value: string) => void;
   del: () => void;
-}
+};
 
 const NoopStorageSlot: StorageSlot = {
   get: () => null,
@@ -61,7 +66,7 @@ const NoopStorageSlot: StorageSlot = {
   del: () => {},
 };
 
-//  Fail-fast, as storage APIs should not be used during the SSR process
+// Fail-fast, as storage APIs should not be used during the SSR process
 function createServerStorageSlot(key: string): StorageSlot {
   function throwError(): never {
     throw new Error(`Illegal storage API usage for storage key "${key}".
@@ -77,16 +82,19 @@ Please only call storage APIs in effects and event handlers.`);
 }
 
 /**
- * Creates an object for accessing a particular key in localStorage.
- * The API is fail-safe, and usage of browser storage should be considered
+ * Creates an interface to work on a particular key in the storage model.
+ * Note that this function only initializes the interface, but doesn't allocate
+ * anything by itself (i.e. no side-effects).
+ *
+ * The API is fail-safe, since usage of browser storage should be considered
  * unreliable. Local storage might simply be unavailable (iframe + browser
  * security) or operations might fail individually. Please assume that using
- * this API can be a NO-OP. See also https://github.com/facebook/docusaurus/issues/6036
+ * this API can be a no-op. See also https://github.com/facebook/docusaurus/issues/6036
  */
-export const createStorageSlot = (
+export function createStorageSlot(
   key: string,
   options?: {persistence?: StorageType},
-): StorageSlot => {
+): StorageSlot {
   if (typeof window === 'undefined') {
     return createServerStorageSlot(key);
   }
@@ -121,10 +129,10 @@ export const createStorageSlot = (
       }
     },
   };
-};
+}
 
 /**
- * Returns a list of all the keys currently stored in browser storage
+ * Returns a list of all the keys currently stored in browser storage,
  * or an empty list if browser storage can't be accessed.
  */
 export function listStorageKeys(

package/src/utils/tagsUtils.ts

@@ -6,6 +6,7 @@
  */
 
 import {translate} from '@docusaurus/Translate';
+import type {TagsListItem} from '@docusaurus/utils';
 
 export const translateTagsPageTitle = (): string =>
   translate({
@@ -14,23 +15,24 @@ export const translateTagsPageTitle = (): string =>
     description: 'The title of the tag list page',
   });
 
-type TagsListItem = Readonly<{name: string; permalink: string; count: number}>; // TODO remove duplicated type :s
-
-export type TagLetterEntry = Readonly<{letter: string; tags: TagsListItem[]}>;
+export type TagLetterEntry = {letter: string; tags: TagsListItem[]};
 
 function getTagLetter(tag: string): string {
-  return tag[0].toUpperCase();
+  return tag[0]!.toUpperCase();
 }
 
+/**
+ * Takes a list of tags (as provided by the content plugins), and groups them by
+ * their initials.
+ */
 export function listTagsByLetters(
   tags: readonly TagsListItem[],
 ): TagLetterEntry[] {
-  // Group by letters
-  const groups: Record<string, TagsListItem[]> = {};
+  const groups: {[initial: string]: TagsListItem[]} = {};
   Object.values(tags).forEach((tag) => {
-    const letter = getTagLetter(tag.name);
-    groups[letter] = groups[letter] ?? [];
-    groups[letter].push(tag);
+    const initial = getTagLetter(tag.label);
+    groups[initial] ??= [];
+    groups[initial]!.push(tag);
   });
 
   return (
@@ -40,7 +42,7 @@ export function listTagsByLetters(
       .map(([letter, letterTags]) => {
         // Sort tags inside a letter
         const sortedTags = letterTags.sort((tag1, tag2) =>
-          tag1.name.localeCompare(tag2.name),
+          tag1.label.localeCompare(tag2.label),
         );
         return {letter, tags: sortedTags};
       })