@docusaurus/theme-common 2.0.0-beta.12faed89d → 2.0.0-beta.13

package/src/utils/docsUtils.tsx

@@ -0,0 +1,185 @@
+/**
+ * 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, {createContext, ReactNode, useContext} from 'react';
+import {useAllDocsData} from '@theme/hooks/useDocs';
+import {
+  PropSidebar,
+  PropSidebarItem,
+  PropSidebarItemCategory,
+  PropVersionDoc,
+  PropVersionMetadata,
+} from '@docusaurus/plugin-content-docs';
+import {isSamePath} from './pathUtils';
+import {useLocation} from '@docusaurus/router';
+
+// TODO not ideal, see also "useDocs"
+export const isDocsPluginEnabled: boolean = !!useAllDocsData;
+
+// Using a Symbol because null is a valid context value (a doc can have no sidebar)
+// Inspired by https://github.com/jamiebuilds/unstated-next/blob/master/src/unstated-next.tsx
+const EmptyContextValue: unique symbol = Symbol('EmptyContext');
+
+const DocsVersionContext = createContext<
+  PropVersionMetadata | typeof EmptyContextValue
+>(EmptyContextValue);
+
+export function DocsVersionProvider({
+  children,
+  version,
+}: {
+  children: ReactNode;
+  version: PropVersionMetadata | typeof EmptyContextValue;
+}): JSX.Element {
+  return (
+    <DocsVersionContext.Provider value={version}>
+      {children}
+    </DocsVersionContext.Provider>
+  );
+}
+
+export function useDocsVersion(): PropVersionMetadata {
+  const version = useContext(DocsVersionContext);
+  if (version === EmptyContextValue) {
+    throw new Error('This hook requires usage of <DocsVersionProvider>');
+  }
+  return version;
+}
+
+export function useDocById(id: string): PropVersionDoc;
+export function useDocById(id: string | undefined): PropVersionDoc | undefined;
+export function useDocById(id: string | undefined): PropVersionDoc | undefined {
+  const version = useDocsVersion();
+  if (!id) {
+    return undefined;
+  }
+  const doc = version.docs[id];
+  if (!doc) {
+    throw new Error(`no version doc found by id=${id}`);
+  }
+  return doc;
+}
+
+const DocsSidebarContext = createContext<
+  PropSidebar | null | typeof EmptyContextValue
+>(EmptyContextValue);
+
+export function DocsSidebarProvider({
+  children,
+  sidebar,
+}: {
+  children: ReactNode;
+  sidebar: PropSidebar | null;
+}): JSX.Element {
+  return (
+    <DocsSidebarContext.Provider value={sidebar}>
+      {children}
+    </DocsSidebarContext.Provider>
+  );
+}
+
+export function useDocsSidebar(): PropSidebar | null {
+  const sidebar = useContext(DocsSidebarContext);
+  if (sidebar === EmptyContextValue) {
+    throw new Error('This hook requires usage of <DocsSidebarProvider>');
+  }
+  return sidebar;
+}
+
+// Use the components props and the sidebar in context
+// to get back the related sidebar category that we want to render
+export function findSidebarCategory(
+  sidebar: PropSidebar,
+  predicate: (category: PropSidebarItemCategory) => boolean,
+): PropSidebarItemCategory | undefined {
+  // eslint-disable-next-line no-restricted-syntax
+  for (const item of sidebar) {
+    if (item.type === 'category') {
+      if (predicate(item)) {
+        return item;
+      } else {
+        const subItem = findSidebarCategory(item.items, predicate);
+        if (subItem) {
+          return subItem;
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+// If a category card has no link => link to the first subItem having a link
+export function findFirstCategoryLink(
+  item: PropSidebarItemCategory,
+): string | undefined {
+  if (item.href) {
+    return item.href;
+  }
+
+  // eslint-disable-next-line no-restricted-syntax
+  for (const subItem of item.items) {
+    if (subItem.type === 'link') {
+      return subItem.href;
+    }
+    if (subItem.type === 'category') {
+      const categoryLink = findFirstCategoryLink(subItem);
+      if (categoryLink) {
+        return categoryLink;
+      }
+    } else {
+      throw new Error(
+        `Unexpected category item type for ${JSON.stringify(subItem)}`,
+      );
+    }
+  }
+  return undefined;
+}
+
+export function useCurrentSidebarCategory(): PropSidebarItemCategory {
+  const {pathname} = useLocation();
+  const sidebar = useDocsSidebar();
+  if (!sidebar) {
+    throw new Error('Unexpected: cant find current sidebar in context');
+  }
+  const category = findSidebarCategory(sidebar, (item) =>
+    isSamePath(item.href, pathname),
+  );
+  if (!category) {
+    throw new Error(
+      `Unexpected: sidebar category could not be found for pathname='${pathname}'.
+Hook useCurrentSidebarCategory() should only be used on Category pages`,
+    );
+  }
+  return category;
+}
+
+function containsActiveSidebarItem(
+  items: PropSidebarItem[],
+  activePath: string,
+): boolean {
+  return items.some((subItem) => isActiveSidebarItem(subItem, activePath));
+}
+
+export function isActiveSidebarItem(
+  item: PropSidebarItem,
+  activePath: string,
+): boolean {
+  const isActive = (testedPath: string | undefined) =>
+    typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
+
+  if (item.type === 'link') {
+    return isActive(item.href);
+  }
+
+  if (item.type === 'category') {
+    return (
+      isActive(item.href) || containsActiveSidebarItem(item.items, activePath)
+    );
+  }
+
+  return false;
+}

package/src/utils/generalUtils.ts

@@ -4,11 +4,12 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
 export const useTitleFormatter = (title?: string | undefined): string => {
-  const {siteConfig = {}} = useDocusaurusContext();
-  const {title: siteTitle, titleDelimiter = '|'} = siteConfig;
+  const {siteConfig} = useDocusaurusContext();
+  const {title: siteTitle, titleDelimiter} = siteConfig;
   return title && title.trim().length
     ? `${title.trim()} ${titleDelimiter} ${siteTitle}`
     : siteTitle;

package/src/utils/historyUtils.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 {useEffect, useRef} from 'react';
+import {useHistory} from '@docusaurus/router';
+import type {Location, Action} from '@docusaurus/history';
+
+type HistoryBlockHandler = (location: Location, action: Action) => void | false;
+
+/*
+Permits to register a handler that will be called on history actions (pop,push,replace)
+If the handler returns false, the navigation transition will be blocked/cancelled
+ */
+export function useHistoryActionHandler(handler: HistoryBlockHandler): void {
+  const {block} = useHistory();
+
+  // Avoid stale closure issues without triggering useless re-renders
+  const lastHandlerRef = useRef(handler);
+  useEffect(() => {
+    lastHandlerRef.current = handler;
+  }, [handler]);
+
+  useEffect(
+    () =>
+      // See https://github.com/remix-run/history/blob/main/docs/blocking-transitions.md
+      block((location, action) => lastHandlerRef.current(location, action)),
+    [block, lastHandlerRef],
+  );
+}
+
+/*
+Permits to register a handler that will be called on history pop navigation (backward/forward)
+If the handler returns false, the backward/forward transition will be blocked
+
+Unfortunately there's no good way to detect the "direction" (backward/forward) of the POP event.
+ */
+export function useHistoryPopHandler(handler: HistoryBlockHandler): void {
+  useHistoryActionHandler((location, action) => {
+    if (action === 'POP') {
+      // Eventually block navigation if handler returns false
+      return handler(location, action);
+    }
+    // Don't block other navigation actions
+    return undefined;
+  });
+}

package/src/utils/jsUtils.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+
+// A replacement of lodash in client code
+
+/**
+ * Gets the duplicate values in an array.
+ * @param arr The array.
+ * @param comparator Compares two values and returns `true` if they are equal (duplicated).
+ * @returns Value of the elements `v` that have a preceding element `u` where `comparator(u, v) === true`. Values within the returned array are not guaranteed to be unique.
+ */
+export function duplicates<T>(
+  arr: readonly T[],
+  comparator: (a: T, b: T) => boolean = (a, b) => a === b,
+): T[] {
+  return arr.filter(
+    (v, vIndex) => arr.findIndex((u) => comparator(u, v)) !== vIndex,
+  );
+}
+
+/**
+ * Remove duplicate array items (similar to _.uniq)
+ * @param arr The array.
+ * @returns An array with duplicate elements removed by reference comparison.
+ */
+export function uniq<T>(arr: T[]): T[] {
+  // Note: had problems with [...new Set()]: https://github.com/facebook/docusaurus/issues/4972#issuecomment-863895061
+  return Array.from(new Set(arr));
+}

package/src/utils/mobileSecondaryMenu.tsx

@@ -29,7 +29,7 @@ type ExtraProps = {
   toggleSidebar: () => void;
 };
 
-export type MobileSecondaryMenuComponent<Props extends unknown> = ComponentType<
+export type MobileSecondaryMenuComponent<Props> = ComponentType<
   Props & ExtraProps
 >;
 
@@ -46,7 +46,11 @@ type ContextValue = ReturnType<typeof useContextValue>;
 
 const Context = createContext<ContextValue | null>(null);
 
-export function MobileSecondaryMenuProvider({children}: {children: ReactNode}) {
+export function MobileSecondaryMenuProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
   return (
     <Context.Provider value={useContextValue()}>{children}</Context.Provider>
   );
@@ -79,13 +83,14 @@ function useShallowMemoizedObject<O extends Record<string, unknown>>(obj: O) {
   return useMemo(
     () => obj,
     // Is this safe?
+    // eslint-disable-next-line react-hooks/exhaustive-deps
     [...Object.keys(obj), ...Object.values(obj)],
   );
 }
 
 // Fill the secondary menu placeholder with some real content
 export function MobileSecondaryMenuFiller<
-  Props extends Record<string, unknown>
+  Props extends Record<string, unknown>,
 >({
   component,
   props,
@@ -103,9 +108,7 @@ export function MobileSecondaryMenuFiller<
     setState({component, props: memoizedProps});
   }, [setState, component, memoizedProps]);
 
-  useEffect(() => {
-    return () => setState(null);
-  }, [setState]);
+  useEffect(() => () => setState(null), [setState]);
 
   return null;
 }

package/src/utils/pathUtils.ts

@@ -10,8 +10,7 @@ export const isSamePath = (
   path1: string | undefined,
   path2: string | undefined,
 ): boolean => {
-  const normalize = (pathname: string | undefined) => {
-    return !pathname || pathname?.endsWith('/') ? pathname : `${pathname}/`;
-  };
+  const normalize = (pathname: string | undefined) =>
+    !pathname || pathname?.endsWith('/') ? pathname : `${pathname}/`;
   return normalize(path1) === normalize(path2);
 };

package/src/utils/reactUtils.tsx

@@ -0,0 +1,34 @@
+/**
+ * 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 {useCallback, useEffect, useLayoutEffect, useRef} from 'react';
+
+// 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 =
+  typeof window !== 'undefined' ? 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 array
+// Useful to avoid React stale closure problems + avoid useless effect re-executions
+//
+// Workaround until the React team recommends a good solution, see https://github.com/facebook/react/issues/16956
+// This generally works has some potential drawbacks, such as https://github.com/facebook/react/issues/16956#issuecomment-536636418
+export function useDynamicCallback<T extends (...args: never[]) => unknown>(
+  callback: T,
+): T {
+  const ref = useRef<T>(callback);
+
+  useIsomorphicLayoutEffect(() => {
+    ref.current = callback;
+  }, [callback]);
+
+  // @ts-expect-error: TODO, not sure how to fix this TS error
+  return useCallback<T>((...args) => ref.current(...args), []);
+}

package/src/utils/regexpUtils.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+
+/**
+ * Utility to convert an optional string into a Regex case sensitive 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/scrollUtils.tsx

@@ -0,0 +1,237 @@
+/**
+ * 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, {
+  createContext,
+  ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from 'react';
+import {useDynamicCallback} from './reactUtils';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+/**
+ * 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
+   */
+  scrollEventsEnabledRef: React.MutableRefObject<boolean>;
+  /**
+   * Enables scroll events in `useScrollPosition`
+   */
+  enableScrollEvents: () => void;
+  /**
+   * Disables 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 = createContext<ScrollController | undefined>(
+  undefined,
+);
+
+export function ScrollControllerProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  return (
+    <ScrollMonitorContext.Provider value={useScrollControllerContextValue()}>
+      {children}
+    </ScrollMonitorContext.Provider>
+  );
+}
+
+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.',
+    );
+  }
+  return context;
+}
+
+const getScrollPosition = (): ScrollPosition | null =>
+  ExecutionEnvironment.canUseDOM
+    ? {
+        scrollX: window.pageXOffset,
+        scrollY: window.pageYOffset,
+      }
+    : null;
+
+type ScrollPosition = {scrollX: number; scrollY: number};
+
+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()!;
+
+      if (dynamicEffect) {
+        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);
+  }, [
+    dynamicEffect,
+    scrollEventsEnabledRef,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    ...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]);
+}
+
+type UseScrollPositionBlockerReturn = {
+  blockElementScrollPositionUntilNextRender: (el: HTMLElement) => void;
+};
+
+/**
+ * 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 GIF here: https://github.com/facebook/docusaurus/pull/5618
+ */
+export function useScrollPositionBlocker(): UseScrollPositionBlockerReturn {
+  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 again the scrollController events
+        if (restored) {
+          const handleScrollRestoreEvent = () => {
+            scrollController.enableScrollEvents();
+            window.removeEventListener('scroll', handleScrollRestoreEvent);
+          };
+          window.addEventListener('scroll', handleScrollRestoreEvent);
+        } else {
+          scrollController.enableScrollEvents();
+        }
+      };
+    },
+    [scrollController, scrollPositionSaver],
+  );
+
+  useLayoutEffect(() => {
+    nextLayoutEffectCallbackRef.current?.();
+  });
+
+  return {
+    blockElementScrollPositionUntilNextRender,
+  };
+}

package/src/utils/storageUtils.ts

@@ -27,7 +27,7 @@ function getBrowserStorage(
     try {
       return window[storageType];
     } catch (e) {
-      logOnceBrowserStorageNotAvailableWarning(e);
+      logOnceBrowserStorageNotAvailableWarning(e as Error);
       return null;
     }
   }
@@ -79,6 +79,10 @@ 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 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 = (
   key: string,
@@ -92,9 +96,28 @@ 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 (e) {
+        console.error(`Docusaurus storage error, can't get key=${key}`, e);
+        return null;
+      }
+    },
+    set: (value) => {
+      try {
+        browserStorage.setItem(key, value);
+      } catch (e) {
+        console.error(`Docusaurus storage error, can't set ${key}=${value}`, e);
+      }
+    },
+    del: () => {
+      try {
+        browserStorage.removeItem(key);
+      } catch (e) {
+        console.error(`Docusaurus storage error, can't delete key=${key}`, e);
+      }
+    },
   };
 };