@docusaurus/theme-common 2.0.0-beta.2 → 2.0.0-beta.22

package/src/utils/reactUtils.tsx

@@ -0,0 +1,129 @@
+/**
+ * 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,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  type ComponentType,
+  type ReactNode,
+} 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...).
+ * 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`).
+ */
+export const useIsomorphicLayoutEffect = ExecutionEnvironment.canUseDOM
+  ? useLayoutEffect
+  : useEffect;
+
+/**
+ * Temporary userland implementation until an official hook is implemented
+ * See RFC: https://github.com/reactjs/rfcs/pull/220
+ *
+ * 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
+ * array. Useful to avoid React stale closure problems + avoid useless effect
+ * re-executions.
+ *
+ * This generally works but has some potential drawbacks, such as
+ * https://github.com/facebook/react/issues/16956#issuecomment-536636418
+ */
+export function useEvent<T extends (...args: never[]) => unknown>(
+  callback: T,
+): T {
+  const ref = useRef<T>(callback);
+
+  useIsomorphicLayoutEffect(() => {
+    ref.current = callback;
+  }, [callback]);
+
+  // @ts-expect-error: TS is right that this callback may be a supertype of T,
+  // 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 ?? ''}`;
+  }
+}
+
+/**
+ * Shallow-memoize an object. This means the returned object will be the same as
+ * the previous render if the property keys and values did not change. This
+ * works for simple cases: when property values are primitives or stable
+ * objects.
+ *
+ * @param obj
+ */
+export function useShallowMemoObject<O extends object>(obj: O): O {
+  const deps = Object.entries(obj);
+  // Sort by keys to make it order-insensitive
+  deps.sort((a, b) => a[0].localeCompare(b[0]));
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return useMemo(() => obj, deps.flat());
+}
+
+type SimpleProvider = ComponentType<{children: ReactNode}>;
+
+/**
+ * Creates a single React provider from an array of existing providers
+ * assuming providers only take "children" as props.
+ *
+ * Prevents the annoying React element nesting
+ * Example here: https://getfrontend.tips/compose-multiple-react-providers/
+ *
+ * The order matters:
+ * - The first provider is at the top of the tree.
+ * - The last provider is the most nested one
+ *
+ * @param providers array of providers to compose
+ */
+export function composeProviders(providers: SimpleProvider[]): SimpleProvider {
+  // Creates a single React component: it's cheaper to compose JSX elements
+  return ({children}) => (
+    <>
+      {providers.reduceRight(
+        (element, CurrentProvider) => (
+          <CurrentProvider>{element}</CurrentProvider>
+        ),
+        children,
+      )}
+    </>
+  );
+}

package/src/utils/regexpUtils.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+
+/**
+ * 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,
+  valueToTest?: string,
+): boolean {
+  if (
+    typeof regexAsString === 'undefined' ||
+    typeof valueToTest === 'undefined'
+  ) {
+    return false;
+  }
+
+  return new RegExp(regexAsString, 'gi').test(valueToTest);
+}

package/src/utils/routesUtils.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 {useMemo} from 'react';
+import generatedRoutes from '@generated/routes';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import type {RouteConfig} from 'react-router-config';
+
+/**
+ * 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);
+}
+
+/**
+ * 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;
+  }
+
+  function isHomeParentRoute(route: RouteConfig): boolean {
+    return route.path === baseUrl && !route.exact;
+  }
+
+  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);
+  }
+
+  return doFindHomePageRoute(initialRoutes);
+}
+
+/**
+ * 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

@@ -0,0 +1,304 @@
+/**
+ * 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,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {useEvent, ReactContextError} from './reactUtils';
+
+type ScrollController = {
+  /** A boolean ref tracking whether scroll events are enabled. */
+  scrollEventsEnabledRef: React.MutableRefObject<boolean>;
+  /** Enable scroll events in `useScrollPosition`. */
+  enableScrollEvents: () => void;
+  /** Disable scroll events in `useScrollPosition`. */
+  disableScrollEvents: () => void;
+};
+
+function useScrollControllerContextValue(): ScrollController {
+  const scrollEventsEnabledRef = useRef(true);
+
+  return useMemo(
+    () => ({
+      scrollEventsEnabledRef,
+      enableScrollEvents: () => {
+        scrollEventsEnabledRef.current = true;
+      },
+      disableScrollEvents: () => {
+        scrollEventsEnabledRef.current = false;
+      },
+    }),
+    [],
+  );
+}
+
+const ScrollMonitorContext = React.createContext<ScrollController | undefined>(
+  undefined,
+);
+
+export function ScrollControllerProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const value = useScrollControllerContextValue();
+  return (
+    <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 ReactContextError('ScrollControllerProvider');
+  }
+  return context;
+}
+
+type ScrollPosition = {scrollX: number; scrollY: number};
+
+const getScrollPosition = (): ScrollPosition | null =>
+  ExecutionEnvironment.canUseDOM
+    ? {
+        scrollX: window.pageXOffset,
+        scrollY: window.pageYOffset,
+      }
+    : null;
+
+/**
+ * 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,
+    lastPosition: ScrollPosition | null,
+  ) => void,
+  deps: unknown[] = [],
+): void {
+  const {scrollEventsEnabledRef} = useScrollController();
+  const lastPositionRef = useRef<ScrollPosition | null>(getScrollPosition());
+
+  const dynamicEffect = useEvent(effect);
+
+  useEffect(() => {
+    const handleScroll = () => {
+      if (!scrollEventsEnabledRef.current) {
+        return;
+      }
+      const currentPosition = getScrollPosition()!;
+      dynamicEffect(currentPosition, lastPositionRef.current);
+      lastPositionRef.current = currentPosition;
+    };
+
+    const opts: AddEventListenerOptions & EventListenerOptions = {
+      passive: true,
+    };
+
+    handleScroll();
+    window.addEventListener('scroll', handleScroll, opts);
+
+    return () => window.removeEventListener('scroll', handleScroll, opts);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dynamicEffect, scrollEventsEnabledRef, ...deps]);
+}
+
+type UseScrollPositionSaver = {
+  /** 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.
+   */
+  restore: () => {restored: boolean};
+};
+
+function useScrollPositionSaver(): UseScrollPositionSaver {
+  const lastElementRef = useRef<{elem: HTMLElement | null; top: number}>({
+    elem: null,
+    top: 0,
+  });
+
+  const save = useCallback((elem: HTMLElement) => {
+    lastElementRef.current = {
+      elem,
+      top: elem.getBoundingClientRect().top,
+    };
+  }, []);
+
+  const restore = useCallback(() => {
+    const {
+      current: {elem, top},
+    } = lastElementRef;
+    if (!elem) {
+      return {restored: false};
+    }
+    const newTop = elem.getBoundingClientRect().top;
+    const heightDiff = newTop - top;
+    if (heightDiff) {
+      window.scrollBy({left: 0, top: heightDiff});
+    }
+    lastElementRef.current = {elem: null, top: 0};
+
+    return {restored: heightDiff !== 0};
+  }, []);
+
+  return useMemo(() => ({save, restore}), [restore, save]);
+}
+
+/**
+ * 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.
+ *
+ * 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 https://github.com/facebook/docusaurus/pull/5618
+ */
+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();
+
+  const nextLayoutEffectCallbackRef = useRef<(() => void) | undefined>(
+    undefined,
+  );
+
+  const blockElementScrollPositionUntilNextRender = useCallback(
+    (el: HTMLElement) => {
+      scrollPositionSaver.save(el);
+      scrollController.disableScrollEvents();
+      nextLayoutEffectCallbackRef.current = () => {
+        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 the
+        // scrollController events again.
+        if (restored) {
+          const handleScrollRestoreEvent = () => {
+            scrollController.enableScrollEvents();
+            window.removeEventListener('scroll', handleScrollRestoreEvent);
+          };
+          window.addEventListener('scroll', handleScrollRestoreEvent);
+        } else {
+          scrollController.enableScrollEvents();
+        }
+      };
+    },
+    [scrollController, scrollPositionSaver],
+  );
+
+  useLayoutEffect(() => {
+    nextLayoutEffectCallbackRef.current?.();
+  });
+
+  return {
+    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 useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useDocsPreferredVersionByPluginId} from '../contexts/docsPreferredVersion';
+
 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,
+  };
+}