@docusaurus/theme-common 2.0.0-beta.8bda3b2db → 2.0.0-beta.9

package/src/utils/__tests__/tocUtils.test.ts

@@ -0,0 +1,197 @@
+/**
+ * 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 {TOCItem} from '@docusaurus/types';
+import {filterTOC} from '../tocUtils';
+
+describe('filterTOC', () => {
+  test('filter a toc with all heading levels', () => {
+    const toc: TOCItem[] = [
+      {
+        id: 'alpha',
+        level: 1,
+        value: 'alpha',
+        children: [
+          {
+            id: 'bravo',
+            level: 2,
+            value: 'Bravo',
+            children: [
+              {
+                id: 'charlie',
+                level: 3,
+                value: 'Charlie',
+                children: [
+                  {
+                    id: 'delta',
+                    level: 4,
+                    value: 'Delta',
+                    children: [
+                      {
+                        id: 'echo',
+                        level: 5,
+                        value: 'Echo',
+                        children: [
+                          {
+                            id: 'foxtrot',
+                            level: 6,
+                            value: 'Foxtrot',
+                            children: [],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ];
+
+    expect(filterTOC({toc, minHeadingLevel: 2, maxHeadingLevel: 2})).toEqual([
+      {
+        id: 'bravo',
+        level: 2,
+        value: 'Bravo',
+        children: [],
+      },
+    ]);
+
+    expect(filterTOC({toc, minHeadingLevel: 3, maxHeadingLevel: 3})).toEqual([
+      {
+        id: 'charlie',
+        level: 3,
+        value: 'Charlie',
+        children: [],
+      },
+    ]);
+
+    expect(filterTOC({toc, minHeadingLevel: 2, maxHeadingLevel: 3})).toEqual([
+      {
+        id: 'bravo',
+        level: 2,
+        value: 'Bravo',
+        children: [
+          {
+            id: 'charlie',
+            level: 3,
+            value: 'Charlie',
+            children: [],
+          },
+        ],
+      },
+    ]);
+
+    expect(filterTOC({toc, minHeadingLevel: 2, maxHeadingLevel: 4})).toEqual([
+      {
+        id: 'bravo',
+        level: 2,
+        value: 'Bravo',
+        children: [
+          {
+            id: 'charlie',
+            level: 3,
+            value: 'Charlie',
+            children: [
+              {
+                id: 'delta',
+                level: 4,
+                value: 'Delta',
+                children: [],
+              },
+            ],
+          },
+        ],
+      },
+    ]);
+  });
+
+  // It's not 100% clear exactly how the TOC should behave under weird heading levels provided by the user
+  // Adding a test so that behavior stays the same over time
+  test('filter invalid heading levels (but possible) TOC', () => {
+    const toc: TOCItem[] = [
+      {
+        id: 'charlie',
+        level: 3,
+        value: 'Charlie',
+        children: [],
+      },
+      {
+        id: 'bravo',
+        level: 2,
+        value: 'Bravo',
+        children: [
+          {
+            id: 'delta',
+            level: 4,
+            value: 'Delta',
+            children: [],
+          },
+        ],
+      },
+    ];
+
+    expect(filterTOC({toc, minHeadingLevel: 2, maxHeadingLevel: 2})).toEqual([
+      {
+        id: 'bravo',
+        level: 2,
+        value: 'Bravo',
+        children: [],
+      },
+    ]);
+
+    expect(filterTOC({toc, minHeadingLevel: 3, maxHeadingLevel: 3})).toEqual([
+      {
+        id: 'charlie',
+        level: 3,
+        value: 'Charlie',
+        children: [],
+      },
+    ]);
+
+    expect(filterTOC({toc, minHeadingLevel: 4, maxHeadingLevel: 4})).toEqual([
+      {
+        id: 'delta',
+        level: 4,
+        value: 'Delta',
+        children: [],
+      },
+    ]);
+
+    expect(filterTOC({toc, minHeadingLevel: 2, maxHeadingLevel: 3})).toEqual([
+      {
+        id: 'charlie',
+        level: 3,
+        value: 'Charlie',
+        children: [],
+      },
+      {
+        id: 'bravo',
+        level: 2,
+        value: 'Bravo',
+        children: [],
+      },
+    ]);
+
+    expect(filterTOC({toc, minHeadingLevel: 3, maxHeadingLevel: 4})).toEqual([
+      {
+        id: 'charlie',
+        level: 3,
+        value: 'Charlie',
+        children: [],
+      },
+      {
+        id: 'delta',
+        level: 4,
+        value: 'Delta',
+        children: [],
+      },
+    ]);
+  });
+});

package/src/utils/announcementBarUtils.tsx

@@ -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 React, {
+  useState,
+  useEffect,
+  useCallback,
+  useMemo,
+  ReactNode,
+  useContext,
+  createContext,
+} from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {createStorageSlot} from './storageUtils';
+import {useThemeConfig} from './useThemeConfig';
+
+export const AnnouncementBarDismissStorageKey =
+  'docusaurus.announcement.dismiss';
+const AnnouncementBarIdStorageKey = 'docusaurus.announcement.id';
+
+const AnnouncementBarDismissStorage = createStorageSlot(
+  AnnouncementBarDismissStorageKey,
+);
+const IdStorage = createStorageSlot(AnnouncementBarIdStorageKey);
+
+const isDismissedInStorage = () =>
+  AnnouncementBarDismissStorage.get() === 'true';
+const setDismissedInStorage = (bool: boolean) =>
+  AnnouncementBarDismissStorage.set(String(bool));
+
+type AnnouncementBarAPI = {
+  readonly isActive: boolean;
+  readonly close: () => void;
+};
+
+const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
+  const {announcementBar} = useThemeConfig();
+  const isBrowser = useIsBrowser();
+
+  const [isClosed, setClosed] = useState(() => {
+    return isBrowser
+      ? // On client navigation: init with localstorage value
+        isDismissedInStorage()
+      : // On server/hydration: always visible to prevent layout shifts (will be hidden with css if needed)
+        false;
+  });
+  // Update state after hydration
+  useEffect(() => {
+    setClosed(isDismissedInStorage());
+  }, []);
+
+  const handleClose = useCallback(() => {
+    setDismissedInStorage(true);
+    setClosed(true);
+  }, []);
+
+  useEffect(() => {
+    if (!announcementBar) {
+      return;
+    }
+    const {id} = announcementBar;
+
+    let viewedId = IdStorage.get();
+
+    // retrocompatibility due to spelling mistake of default id
+    // see https://github.com/facebook/docusaurus/issues/3338
+    if (viewedId === 'annoucement-bar') {
+      viewedId = 'announcement-bar';
+    }
+
+    const isNewAnnouncement = id !== viewedId;
+
+    IdStorage.set(id);
+
+    if (isNewAnnouncement) {
+      setDismissedInStorage(false);
+    }
+
+    if (isNewAnnouncement || !isDismissedInStorage()) {
+      setClosed(false);
+    }
+  }, [announcementBar]);
+
+  return useMemo(() => {
+    return {
+      isActive: !!announcementBar && !isClosed,
+      close: handleClose,
+    };
+  }, [announcementBar, isClosed, handleClose]);
+};
+
+const AnnouncementBarContext = createContext<AnnouncementBarAPI | null>(null);
+
+export const AnnouncementBarProvider = ({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element => {
+  const value = useAnnouncementBarContextValue();
+  return (
+    <AnnouncementBarContext.Provider value={value}>
+      {children}
+    </AnnouncementBarContext.Provider>
+  );
+};
+
+export const useAnnouncementBar = (): AnnouncementBarAPI => {
+  const api = useContext(AnnouncementBarContext);
+  if (!api) {
+    throw new Error(
+      'useAnnouncementBar(): AnnouncementBar not found in React context: make sure to use the AnnouncementBarProvider on top of the tree',
+    );
+  }
+  return api;
+};

package/src/utils/docsPreferredVersion/DocsPreferredVersionProvider.tsx

@@ -15,7 +15,7 @@ import React, {
 import {useThemeConfig, DocsVersionPersistence} from '../useThemeConfig';
 import {isDocsPluginEnabled} from '../docsUtils';
 
-import {useAllDocsData} from '@theme/hooks/useDocs';
+import {useAllDocsData, GlobalPluginData} from '@theme/hooks/useDocs';
 
 import DocsPreferredVersionStorage from './DocsPreferredVersionStorage';
 
@@ -54,7 +54,7 @@ function readStorageState({
 }: {
   pluginIds: string[];
   versionPersistence: DocsVersionPersistence;
-  allDocsData: any; // TODO find a way to type it :(
+  allDocsData: Record<string, GlobalPluginData>;
 }): DocsPreferredVersionState {
   // The storage value we read might be stale,
   // and belong to a version that does not exist in the site anymore
@@ -68,7 +68,7 @@ function readStorageState({
     );
     const pluginData = allDocsData[pluginId];
     const versionExists = pluginData.versions.some(
-      (version: any) => version.name === preferredVersionNameUnsafe,
+      (version) => version.name === preferredVersionNameUnsafe,
     );
     if (versionExists) {
       return {preferredVersionName: preferredVersionNameUnsafe};
@@ -120,7 +120,7 @@ function useContextValue() {
     return {
       savePreferredVersion,
     };
-  }, [setState]);
+  }, [versionPersistence]);
 
   return [state, api] as const;
 }

package/src/utils/docsPreferredVersion/useDocsPreferredVersion.ts

@@ -6,38 +6,40 @@
  */
 import {useCallback} from 'react';
 import {useDocsPreferredVersionContext} from './DocsPreferredVersionProvider';
-import {useAllDocsData, useDocsData} from '@theme/hooks/useDocs';
+import {useAllDocsData, useDocsData, GlobalVersion} from '@theme/hooks/useDocs';
 
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
 
-// TODO improve typing
-
 // Note, the preferredVersion attribute will always be null before mount
 export function useDocsPreferredVersion(
   pluginId: string | undefined = DEFAULT_PLUGIN_ID,
-) {
+): {
+  preferredVersion: GlobalVersion | null | undefined;
+  savePreferredVersionName: (versionName: string) => void;
+} {
   const docsData = useDocsData(pluginId);
   const [state, api] = useDocsPreferredVersionContext();
 
   const {preferredVersionName} = state[pluginId];
 
   const preferredVersion = preferredVersionName
-    ? docsData.versions.find(
-        (version: any) => version.name === preferredVersionName,
-      )
+    ? docsData.versions.find((version) => version.name === preferredVersionName)
     : null;
 
   const savePreferredVersionName = useCallback(
     (versionName: string) => {
       api.savePreferredVersion(pluginId, versionName);
     },
-    [api],
+    [api, pluginId],
   );
 
   return {preferredVersion, savePreferredVersionName} as const;
 }
 
-export function useDocsPreferredVersionByPluginId(): Record<string, any> {
+export function useDocsPreferredVersionByPluginId(): Record<
+  string,
+  GlobalVersion | null | undefined
+> {
   const allDocsData = useAllDocsData();
   const [state] = useDocsPreferredVersionContext();
 
@@ -47,17 +49,14 @@ export function useDocsPreferredVersionByPluginId(): Record<string, any> {
 
     return preferredVersionName
       ? docsData.versions.find(
-          (version: any) => version.name === preferredVersionName,
+          (version) => version.name === preferredVersionName,
         )
       : null;
   }
 
   const pluginIds = Object.keys(allDocsData);
 
-  const result: Record<
-    string,
-    any // TODO find a way to type this properly!
-  > = {};
+  const result: Record<string, GlobalVersion | null | undefined> = {};
   pluginIds.forEach((pluginId) => {
     result[pluginId] = getPluginIdPreferredVersion(pluginId);
   });

package/src/utils/generalUtils.ts

@@ -7,8 +7,8 @@
 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
+    return block((location, action) => {
+      return 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,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.
+ */
+
+// 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,
+  );
+}

package/src/utils/mobileSecondaryMenu.tsx

@@ -0,0 +1,116 @@
+/**
+ * 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,
+  ReactNode,
+  useContext,
+  createContext,
+  useEffect,
+  ComponentType,
+  useMemo,
+} from 'react';
+
+/*
+The idea behind all this is that a specific component must be able to fill a placeholder in the generic layout
+The doc page should be able to fill the secondary menu of the main mobile navbar.
+This permits to reduce coupling between the main layout and the specific page.
+
+This kind of feature is often called portal/teleport/gateway... 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.
+ */
+
+type ExtraProps = {
+  toggleSidebar: () => void;
+};
+
+export type MobileSecondaryMenuComponent<Props extends unknown> = ComponentType<
+  Props & ExtraProps
+>;
+
+type State = {
+  component: MobileSecondaryMenuComponent<unknown>;
+  props: unknown;
+} | null;
+
+function useContextValue() {
+  return useState<State>(null);
+}
+
+type ContextValue = ReturnType<typeof useContextValue>;
+
+const Context = createContext<ContextValue | null>(null);
+
+export function MobileSecondaryMenuProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  return (
+    <Context.Provider value={useContextValue()}>{children}</Context.Provider>
+  );
+}
+
+function useMobileSecondaryMenuContext(): ContextValue {
+  const value = useContext(Context);
+  if (value === null) {
+    throw new Error(
+      'MobileSecondaryMenuProvider was not used correctly, context value is null',
+    );
+  }
+  return value;
+}
+
+export function useMobileSecondaryMenuRenderer(): (
+  extraProps: ExtraProps,
+) => ReactNode | undefined {
+  const [state] = useMobileSecondaryMenuContext();
+  if (state) {
+    const Comp = state.component;
+    return function render(extraProps) {
+      return <Comp {...state.props} {...extraProps} />;
+    };
+  }
+  return () => undefined;
+}
+
+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>,
+>({
+  component,
+  props,
+}: {
+  component: MobileSecondaryMenuComponent<Props & ExtraProps>;
+  props: Props;
+}): JSX.Element | null {
+  const [, setState] = useMobileSecondaryMenuContext();
+
+  // To avoid useless context re-renders, props are memoized shallowly
+  const memoizedProps = useShallowMemoizedObject(props);
+
+  useEffect(() => {
+    // @ts-expect-error: context is not 100% typesafe but it's ok
+    setState({component, props: memoizedProps});
+  }, [setState, component, memoizedProps]);
+
+  useEffect(() => {
+    return () => setState(null);
+  }, [setState]);
+
+  return null;
+}

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);
+}