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

package/src/utils/codeBlockUtils.ts

@@ -7,8 +7,8 @@
 
 import rangeParser from 'parse-numeric-range';
 
-const codeBlockTitleRegex = /title=(["'])(.*?)\1/;
-const highlightLinesRangeRegex = /{([\d,-]+)}/;
+const codeBlockTitleRegex = /title=(?<quote>["'])(?<title>.*?)\1/;
+const highlightLinesRangeRegex = /{(?<range>[\d,-]+)}/;
 
 const commentTypes = ['js', 'jsBlock', 'jsx', 'python', 'html'] as const;
 type CommentType = typeof commentTypes[number];
@@ -89,7 +89,7 @@ const magicCommentDirectiveRegex = (lang: string) => {
 };
 
 export function parseCodeBlockTitle(metastring?: string): string {
-  return metastring?.match(codeBlockTitleRegex)?.[2] ?? '';
+  return metastring?.match(codeBlockTitleRegex)?.groups!.title ?? '';
 }
 
 export function parseLanguage(className: string): string | undefined {
@@ -114,7 +114,8 @@ export function parseLines(
   let code = content.replace(/\n$/, '');
   // Highlighted lines specified in props: don't parse the content
   if (metastring && highlightLinesRangeRegex.test(metastring)) {
-    const highlightLinesRange = metastring.match(highlightLinesRangeRegex)![1];
+    const highlightLinesRange = metastring.match(highlightLinesRangeRegex)!
+      .groups!.range;
     const highlightLines = rangeParser(highlightLinesRange)
       .filter((n) => n > 0)
       .map((n) => n - 1);

package/src/utils/colorModeUtils.tsx

@@ -24,7 +24,8 @@ type ColorModeContextValue = {
   readonly setDarkTheme: () => void;
 };
 
-const ThemeStorage = createStorageSlot('theme');
+const ThemeStorageKey = 'theme';
+const ThemeStorage = createStorageSlot(ThemeStorageKey);
 
 const themes = {
   light: 'light',
@@ -45,7 +46,7 @@ const getInitialTheme = (defaultMode: Themes | undefined): Themes => {
 };
 
 const storeTheme = (newTheme: Themes) => {
-  createStorageSlot('theme').set(coerceToTheme(newTheme));
+  ThemeStorage.set(coerceToTheme(newTheme));
 };
 
 function useColorModeContextValue(): ColorModeContextValue {
@@ -69,29 +70,49 @@ function useColorModeContextValue(): ColorModeContextValue {
 
   useEffect(() => {
     if (disableSwitch) {
-      return;
+      return undefined;
     }
-
-    try {
-      const storedTheme = ThemeStorage.get();
-      if (storedTheme !== null) {
-        setTheme(coerceToTheme(storedTheme));
+    const onChange = (e: StorageEvent) => {
+      if (e.key !== ThemeStorageKey) {
+        return;
       }
-    } catch (err) {
-      console.error(err);
-    }
+      try {
+        const storedTheme = ThemeStorage.get();
+        if (storedTheme !== null) {
+          setTheme(coerceToTheme(storedTheme));
+        }
+      } catch (err) {
+        console.error(err);
+      }
+    };
+    window.addEventListener('storage', onChange);
+    return () => {
+      window.removeEventListener('storage', onChange);
+    };
   }, [disableSwitch, setTheme]);
 
+  // PCS is coerced to light mode when printing, which causes the color mode to
+  // be reset to dark when exiting print mode, disregarding user settings. When
+  // the listener fires only because of a print/screen switch, we don't change
+  // color mode. See https://github.com/facebook/docusaurus/pull/6490
+  const previousMediaIsPrint = React.useRef(false);
+
   useEffect(() => {
     if (disableSwitch && !respectPrefersColorScheme) {
-      return;
+      return undefined;
     }
-
-    window
-      .matchMedia('(prefers-color-scheme: dark)')
-      .addListener(({matches}) => {
-        setTheme(matches ? themes.dark : themes.light);
-      });
+    const mql = window.matchMedia('(prefers-color-scheme: dark)');
+    const onChange = ({matches}: MediaQueryListEvent) => {
+      if (window.matchMedia('print').matches || previousMediaIsPrint.current) {
+        previousMediaIsPrint.current = window.matchMedia('print').matches;
+        return;
+      }
+      setTheme(matches ? themes.dark : themes.light);
+    };
+    mql.addListener(onChange);
+    return () => {
+      mql.removeListener(onChange);
+    };
   }, [disableSwitch, respectPrefersColorScheme]);
 
   return {

package/src/utils/docsPreferredVersion/DocsPreferredVersionProvider.tsx

@@ -76,10 +76,9 @@ function readStorageState({
     );
     if (versionExists) {
       return {preferredVersionName: preferredVersionNameUnsafe};
-    } else {
-      DocsPreferredVersionStorage.clear(pluginId, versionPersistence);
-      return {preferredVersionName: null};
     }
+    DocsPreferredVersionStorage.clear(pluginId, versionPersistence);
+    return {preferredVersionName: null};
   }
 
   const initialState: DocsPreferredVersionState = {};
@@ -144,9 +143,8 @@ export function DocsPreferredVersionContextProvider({
         {children}
       </DocsPreferredVersionContextProviderUnsafe>
     );
-  } else {
-    return children;
   }
+  return children;
 }
 
 function DocsPreferredVersionContextProviderUnsafe({

package/src/utils/docsUtils.tsx

@@ -6,13 +6,17 @@
  */
 
 import React, {createContext, type ReactNode, useContext} from 'react';
-import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
+import {
+  useActivePlugin,
+  useAllDocsData,
+} from '@docusaurus/plugin-content-docs/client';
 import type {
   PropSidebar,
   PropSidebarItem,
   PropSidebarItemCategory,
   PropVersionDoc,
   PropVersionMetadata,
+  PropSidebarBreadcrumbsItem,
 } from '@docusaurus/plugin-content-docs';
 import {isSamePath} from './pathUtils';
 import {useLocation} from '@docusaurus/router';
@@ -20,7 +24,7 @@ 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)
+// Using a Symbol because null is a valid context value (a doc with no sidebar)
 // Inspired by https://github.com/jamiebuilds/unstated-next/blob/master/src/unstated-next.tsx
 const EmptyContextValue: unique symbol = Symbol('EmptyContext');
 
@@ -96,16 +100,14 @@ 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;
-        }
+      }
+      const subItem = findSidebarCategory(item.items, predicate);
+      if (subItem) {
+        return subItem;
       }
     }
   }
@@ -120,16 +122,16 @@ export function findFirstCategoryLink(
     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') {
+    } else if (subItem.type === 'category') {
       const categoryLink = findFirstCategoryLink(subItem);
       if (categoryLink) {
         return categoryLink;
       }
+    } else if (subItem.type === 'html') {
+      // skip
     } else {
       throw new Error(
         `Unexpected category item type for ${JSON.stringify(subItem)}`,
@@ -183,3 +185,46 @@ export function isActiveSidebarItem(
 
   return false;
 }
+
+export function getBreadcrumbs({
+  sidebar,
+  pathname,
+}: {
+  sidebar: PropSidebar;
+  pathname: string;
+}): PropSidebarBreadcrumbsItem[] {
+  const breadcrumbs: PropSidebarBreadcrumbsItem[] = [];
+
+  function extract(items: PropSidebar) {
+    for (const item of items) {
+      if (
+        item.type === 'category' &&
+        (isSamePath(item.href, pathname) || extract(item.items))
+      ) {
+        breadcrumbs.push(item);
+        return true;
+      } else if (item.type === 'link' && isSamePath(item.href, pathname)) {
+        breadcrumbs.push(item);
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  extract(sidebar);
+
+  return breadcrumbs.reverse();
+}
+
+export function useSidebarBreadcrumbs(): PropSidebarBreadcrumbsItem[] | null {
+  const sidebar = useDocsSidebar();
+  const {pathname} = useLocation();
+  const breadcrumbsOption = useActivePlugin()?.pluginData.breadcrumbs;
+
+  if (breadcrumbsOption === false || !sidebar) {
+    return null;
+  }
+
+  return getBreadcrumbs({sidebar, pathname});
+}

package/src/utils/historyUtils.ts

@@ -7,13 +7,14 @@
 
 import {useEffect, useRef} from 'react';
 import {useHistory} from '@docusaurus/router';
-import type {Location, Action} from '@docusaurus/history';
+import type {Location, Action} from '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
+/**
+ * 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();
@@ -32,11 +33,11 @@ export function useHistoryActionHandler(handler: HistoryBlockHandler): void {
   );
 }
 
-/*
-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.
+/**
+ * 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) => {

package/src/utils/jsUtils.ts

@@ -10,8 +10,11 @@
 /**
  * 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.
+ * @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[],

package/src/utils/mobileSecondaryMenu.tsx

@@ -16,12 +16,13 @@ import React, {
 } 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.
+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
+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.
  */
 

package/src/utils/pathUtils.ts

@@ -5,12 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// Compare the 2 paths, ignoring trailing /
+// Compare the 2 paths, case insensitive and ignoring trailing slash
 export const isSamePath = (
   path1: string | undefined,
   path2: string | undefined,
 ): boolean => {
   const normalize = (pathname: string | undefined) =>
-    !pathname || pathname?.endsWith('/') ? pathname : `${pathname}/`;
+    (!pathname || pathname?.endsWith('/')
+      ? pathname
+      : `${pathname}/`
+    )?.toLowerCase();
   return normalize(path1) === normalize(path2);
 };

package/src/utils/reactUtils.tsx

@@ -7,19 +7,27 @@
 
 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)
+/**
+ * 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
+/**
+ * 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 but 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 {
@@ -29,6 +37,7 @@ export function useDynamicCallback<T extends (...args: never[]) => unknown>(
     ref.current = callback;
   }, [callback]);
 
-  // @ts-expect-error: TODO, not sure how to fix this TS error
+  // @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), []);
 }

package/src/utils/regexpUtils.ts

@@ -6,7 +6,7 @@
  */
 
 /**
- * Utility to convert an optional string into a Regex case insensitive and global
+ * Converts an optional string into a Regex case insensitive and global
  */
 export function isRegexpStringMatch(
   regexAsString?: string,

package/src/utils/routesUtils.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 GeneratedRoutes, {type Route} from '@generated/routes';
+import {useMemo} from 'react';
+
+function isHomePageRoute(route: Route): boolean {
+  return route.path === '/' && route.exact === true;
+}
+
+function isHomeParentRoute(route: Route): boolean {
+  return route.path === '/' && route.exact === false;
+}
+
+// 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;
+  }
+  const homePage = routes.find(isHomePageRoute);
+  if (homePage) {
+    return homePage;
+  }
+  const indexSubRoutes = routes
+    .filter(isHomeParentRoute)
+    .flatMap((route) => route.routes ?? []);
+  return findHomePageRoute(indexSubRoutes);
+}
+
+export function useHomePageRoute(): Route | undefined {
+  return useMemo(() => findHomePageRoute(), []);
+}

package/src/utils/storageUtils.ts

@@ -11,8 +11,8 @@ 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 browser storage is unavailable (like running Docusaurus in
+// iframe) See https://github.com/facebook/docusaurus/pull/4501
 function getBrowserStorage(
   storageType: StorageType = DefaultStorageType,
 ): Storage | null {
@@ -23,13 +23,12 @@ function getBrowserStorage(
   }
   if (storageType === 'none') {
     return null;
-  } else {
-    try {
-      return window[storageType];
-    } catch (e) {
-      logOnceBrowserStorageNotAvailableWarning(e as Error);
-      return null;
-    }
+  }
+  try {
+    return window[storageType];
+  } catch (err) {
+    logOnceBrowserStorageNotAvailableWarning(err as Error);
+    return null;
   }
 }
 
@@ -79,10 +78,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
+ * 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,
@@ -99,23 +98,26 @@ export const createStorageSlot = (
     get: () => {
       try {
         return browserStorage.getItem(key);
-      } catch (e) {
-        console.error(`Docusaurus storage error, can't get key=${key}`, e);
+      } catch (err) {
+        console.error(`Docusaurus storage error, can't get key=${key}`, err);
         return null;
       }
     },
     set: (value) => {
       try {
         browserStorage.setItem(key, value);
-      } catch (e) {
-        console.error(`Docusaurus storage error, can't set ${key}=${value}`, e);
+      } catch (err) {
+        console.error(
+          `Docusaurus storage error, can't set ${key}=${value}`,
+          err,
+        );
       }
     },
     del: () => {
       try {
         browserStorage.removeItem(key);
-      } catch (e) {
-        console.error(`Docusaurus storage error, can't delete key=${key}`, e);
+      } catch (err) {
+        console.error(`Docusaurus storage error, can't delete key=${key}`, err);
       }
     },
   };

package/src/utils/tocUtils.ts

@@ -8,18 +8,64 @@
 import {useMemo} from 'react';
 import type {TOCItem} from '@docusaurus/types';
 
-type FilterTOCParam = {
-  toc: readonly TOCItem[];
-  minHeadingLevel: number;
-  maxHeadingLevel: number;
+export type TOCTreeNode = {
+  readonly value: string;
+  readonly id: string;
+  readonly level: number;
+  readonly children: readonly TOCTreeNode[];
 };
 
-export function filterTOC({
+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(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;
+}
+
+export function useTreeifiedTOC(toc: TOCItem[]): readonly TOCTreeNode[] {
+  return useMemo(() => treeifyTOC(toc), [toc]);
+}
+
+function filterTOC({
   toc,
   minHeadingLevel,
   maxHeadingLevel,
-}: FilterTOCParam): TOCItem[] {
-  function isValid(item: TOCItem) {
+}: {
+  toc: readonly TOCTreeNode[];
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+}): TOCTreeNode[] {
+  function isValid(item: TOCTreeNode) {
     return item.level >= minHeadingLevel && item.level <= maxHeadingLevel;
   }
 
@@ -36,20 +82,27 @@ export function filterTOC({
           children: filteredChildren,
         },
       ];
-    } else {
-      return filteredChildren;
     }
+    return filteredChildren;
   });
 }
 
-// Memoize potentially expensive filtering logic
-export function useTOCFilter({
+export function useFilteredAndTreeifiedTOC({
   toc,
   minHeadingLevel,
   maxHeadingLevel,
-}: FilterTOCParam): readonly TOCItem[] {
+}: {
+  toc: readonly TOCItem[];
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+}): readonly TOCTreeNode[] {
   return useMemo(
-    () => filterTOC({toc, minHeadingLevel, maxHeadingLevel}),
+    () =>
+      // Note: 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]
+      filterTOC({toc: treeifyTOC(toc), minHeadingLevel, maxHeadingLevel}),
     [toc, minHeadingLevel, maxHeadingLevel],
   );
 }

package/src/utils/useAlternatePageUtils.ts

@@ -39,14 +39,15 @@ export function useAlternatePageUtils(): {
       : `${baseUrlUnlocalized}${locale}/`;
   }
 
-  // TODO support correct alternate url when localized site is deployed on another domain
+  // TODO support correct alternate url when localized site is deployed on
+  // another domain
   function createUrl({
     locale,
     fullyQualified,
   }: {
     locale: string;
-    // For hreflang SEO headers, we need it to be fully qualified (full protocol/domain/path...)
-    // For locale dropdown, using a path is good enough
+    // For hreflang SEO headers, we need it to be fully qualified (full
+    // protocol/domain/path...) or locale dropdown, using a path is good enough
     fullyQualified: boolean;
   }) {
     return `${fullyQualified ? url : ''}${getLocalizedBaseUrl(

package/src/utils/useContextualSearchFilters.ts

@@ -18,8 +18,8 @@ export type useContextualSearchFiltersReturns = {
   tags: string[];
 };
 
-// We may want to support multiple search engines, don't couple that to Algolia/DocSearch
-// Maybe users will want to use its own search engine solution
+// We may want to support multiple search engines, don't couple that to
+// Algolia/DocSearch. Maybe users want to use their own search engine solution
 export function useContextualSearchFilters(): useContextualSearchFiltersReturns {
   const {i18n} = useDocusaurusContext();
   const allDocsData = useAllDocsData();