@docusaurus/theme-common 2.0.0-beta.1ec2c95e3 → 2.0.0-beta.21

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 {useDynamicCallback, 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 = useDynamicCallback(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,
+  };
+}

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 {
@@ -23,21 +27,21 @@ function getBrowserStorage(
   }
   if (storageType === 'none') {
     return null;
-  } else {
-    try {
-      return window[storageType];
-    } catch (e) {
-      logOnceBrowserStorageNotAvailableWarning(e);
-      return null;
-    }
+  }
+  try {
+    return window[storageType];
+  } catch (err) {
+    logOnceBrowserStorageNotAvailableWarning(err as Error);
+    return null;
   }
 }
 
+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(
@@ -50,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,
@@ -62,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}".
@@ -78,12 +82,19 @@ Please only call storage APIs in effects and event handlers.`);
 }
 
 /**
- * Creates an object for accessing a particular key in localStorage.
+ * 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
  */
-export const createStorageSlot = (
+export function createStorageSlot(
   key: string,
   options?: {persistence?: StorageType},
-): StorageSlot => {
+): StorageSlot {
   if (typeof window === 'undefined') {
     return createServerStorageSlot(key);
   }
@@ -92,14 +103,36 @@ export const createStorageSlot = (
     return NoopStorageSlot;
   }
   return {
-    get: () => browserStorage.getItem(key),
-    set: (value) => browserStorage.setItem(key, value),
-    del: () => browserStorage.removeItem(key),
+    get: () => {
+      try {
+        return browserStorage.getItem(key);
+      } catch (err) {
+        console.error(`Docusaurus storage error, can't get key=${key}`, err);
+        return null;
+      }
+    },
+    set: (value) => {
+      try {
+        browserStorage.setItem(key, value);
+      } catch (err) {
+        console.error(
+          `Docusaurus storage error, can't set ${key}=${value}`,
+          err,
+        );
+      }
+    },
+    del: () => {
+      try {
+        browserStorage.removeItem(key);
+      } catch (err) {
+        console.error(`Docusaurus storage error, can't delete key=${key}`, err);
+      }
+    },
   };
-};
+}
 
 /**
- * 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

@@ -0,0 +1,50 @@
+/**
+ * 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 {translate} from '@docusaurus/Translate';
+import type {TagsListItem} from '@docusaurus/utils';
+
+export const translateTagsPageTitle = (): string =>
+  translate({
+    id: 'theme.tags.tagsPageTitle',
+    message: 'Tags',
+    description: 'The title of the tag list page',
+  });
+
+export type TagLetterEntry = {letter: string; tags: TagsListItem[]};
+
+function getTagLetter(tag: string): string {
+  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[] {
+  const groups: {[initial: string]: TagsListItem[]} = {};
+  Object.values(tags).forEach((tag) => {
+    const initial = getTagLetter(tag.label);
+    groups[initial] ??= [];
+    groups[initial]!.push(tag);
+  });
+
+  return (
+    Object.entries(groups)
+      // Sort letters
+      .sort(([letter1], [letter2]) => letter1.localeCompare(letter2))
+      .map(([letter, letterTags]) => {
+        // Sort tags inside a letter
+        const sortedTags = letterTags.sort((tag1, tag2) =>
+          tag1.label.localeCompare(tag2.label),
+        );
+        return {letter, tags: sortedTags};
+      })
+  );
+}

package/src/utils/tocUtils.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 type {TOCItem} from '@docusaurus/mdx-loader';
+
+export type TOCTreeNode = {
+  readonly value: string;
+  readonly id: string;
+  readonly level: number;
+  readonly children: readonly TOCTreeNode[];
+};
+
+function treeifyTOC(flatTOC: readonly TOCItem[]): TOCTreeNode[] {
+  const headings = flatTOC.map((heading) => ({
+    ...heading,
+    parentIndex: -1,
+    children: [] as TOCTreeNode[],
+  }));
+
+  // Keep track of which previous index would be the current heading's direct
+  // parent. Each entry <i> is the last index of the `headings` array at heading
+  // level <i>. We will modify these indices as we iterate through all headings.
+  // e.g. if an ### H3 was last seen at index 2, then prevIndexForLevel[3] === 2
+  // indices 0 and 1 will remain unused.
+  const prevIndexForLevel = Array<number>(7).fill(-1);
+
+  headings.forEach((curr, currIndex) => {
+    // Take the last seen index for each ancestor level. the highest index will
+    // be the direct ancestor of the current heading.
+    const ancestorLevelIndexes = prevIndexForLevel.slice(2, curr.level);
+    curr.parentIndex = Math.max(...ancestorLevelIndexes);
+    // Mark that curr.level was last seen at the current index.
+    prevIndexForLevel[curr.level] = currIndex;
+  });
+
+  const rootNodes: TOCTreeNode[] = [];
+
+  // For a given parentIndex, add each Node into that parent's `children` array
+  headings.forEach((heading) => {
+    const {parentIndex, ...rest} = heading;
+    if (parentIndex >= 0) {
+      headings[parentIndex]!.children.push(rest);
+    } else {
+      rootNodes.push(rest);
+    }
+  });
+  return rootNodes;
+}
+
+/**
+ * Takes a flat TOC list (from the MDX loader) and treeifies it into what the
+ * TOC components expect. Memoized for performance.
+ */
+export function useTreeifiedTOC(toc: TOCItem[]): readonly TOCTreeNode[] {
+  return useMemo(() => treeifyTOC(toc), [toc]);
+}
+
+function filterTOC({
+  toc,
+  minHeadingLevel,
+  maxHeadingLevel,
+}: {
+  toc: readonly TOCTreeNode[];
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+}): TOCTreeNode[] {
+  function isValid(item: TOCTreeNode) {
+    return item.level >= minHeadingLevel && item.level <= maxHeadingLevel;
+  }
+
+  return toc.flatMap((item) => {
+    const filteredChildren = filterTOC({
+      toc: item.children,
+      minHeadingLevel,
+      maxHeadingLevel,
+    });
+    if (isValid(item)) {
+      return [
+        {
+          ...item,
+          children: filteredChildren,
+        },
+      ];
+    }
+    return filteredChildren;
+  });
+}
+
+/**
+ * Takes a flat TOC list (from the MDX loader) and treeifies it into what the
+ * TOC components expect, applying the `minHeadingLevel` and `maxHeadingLevel`.
+ * Memoized for performance.
+ *
+ * **Important**: this is not the same as `useTreeifiedTOC(toc.filter(...))`,
+ * because we have to filter the TOC after it has been treeified. This is mostly
+ * to ensure that weird TOC structures preserve their semantics. For example, an
+ * h3-h2-h4 sequence should not be treeified as an "h3 > h4" hierarchy with
+ * min=3, max=4, but should rather be "[h3, h4]" (since the h2 heading has split
+ * the two headings and they are not parent-children)
+ */
+export function useFilteredAndTreeifiedTOC({
+  toc,
+  minHeadingLevel,
+  maxHeadingLevel,
+}: {
+  toc: readonly TOCItem[];
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+}): readonly TOCTreeNode[] {
+  return useMemo(
+    () => filterTOC({toc: treeifyTOC(toc), minHeadingLevel, maxHeadingLevel}),
+    [toc, minHeadingLevel, maxHeadingLevel],
+  );
+}