@docusaurus/theme-common 2.0.0-beta.17 → 2.0.0-beta.18

package/src/utils/docsUtils.tsx

@@ -5,57 +5,32 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {createContext, type ReactNode, useContext} from 'react';
 import {
-  useActivePlugin,
   useAllDocsData,
+  useActivePlugin,
 } from '@docusaurus/plugin-content-docs/client';
 import type {
   PropSidebar,
   PropSidebarItem,
   PropSidebarItemCategory,
   PropVersionDoc,
-  PropVersionMetadata,
   PropSidebarBreadcrumbsItem,
 } from '@docusaurus/plugin-content-docs';
-import {isSamePath} from './pathUtils';
-import {ReactContextError} from './reactUtils';
+import {useDocsVersion} from '../contexts/docsVersion';
+import {useDocsSidebar} from '../contexts/docsSidebar';
+import {isSamePath} from './routesUtils';
 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 with 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 ReactContextError('DocsVersionProvider');
-  }
-  return version;
-}
-
+/**
+ * A null-safe way to access a doc's data by ID in the active version.
+ */
 export function useDocById(id: string): PropVersionDoc;
+/**
+ * A null-safe way to access a doc's data by ID in the active version.
+ */
 export function useDocById(id: string | undefined): PropVersionDoc | undefined;
 export function useDocById(id: string | undefined): PropVersionDoc | undefined {
   const version = useDocsVersion();
@@ -69,34 +44,9 @@ export function useDocById(id: string | undefined): PropVersionDoc | undefined {
   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 ReactContextError('DocsSidebarProvider');
-  }
-  return sidebar;
-}
-
-// Use the components props and the sidebar in context
-// to get back the related sidebar category that we want to render
+/**
+ * Pure function, similar to `Array#find`, but works on the sidebar tree.
+ */
 export function findSidebarCategory(
   sidebar: PropSidebar,
   predicate: (category: PropSidebarItemCategory) => boolean,
@@ -115,7 +65,10 @@ export function findSidebarCategory(
   return undefined;
 }
 
-// If a category card has no link => link to the first subItem having a link
+/**
+ * Best effort to assign a link to a sidebar category. If the category doesn't
+ * have a link itself, we link to the first sub item with a link.
+ */
 export function findFirstCategoryLink(
   item: PropSidebarItemCategory,
 ): string | undefined {
@@ -142,6 +95,10 @@ export function findFirstCategoryLink(
   return undefined;
 }
 
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
 export function useCurrentSidebarCategory(): PropSidebarItemCategory {
   const {pathname} = useLocation();
   const sidebar = useDocsSidebar();
@@ -153,60 +110,64 @@ export function useCurrentSidebarCategory(): PropSidebarItemCategory {
   );
   if (!category) {
     throw new Error(
-      `Unexpected: sidebar category could not be found for pathname='${pathname}'.
-Hook useCurrentSidebarCategory() should only be used on Category pages`,
+      `${pathname} is not associated with a category. useCurrentSidebarCategory() should only be used on category index pages.`,
     );
   }
   return category;
 }
 
-function containsActiveSidebarItem(
+const isActive = (testedPath: string | undefined, activePath: string) =>
+  typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
+const containsActiveSidebarItem = (
   items: PropSidebarItem[],
   activePath: string,
-): boolean {
-  return items.some((subItem) => isActiveSidebarItem(subItem, activePath));
-}
+) => items.some((subItem) => isActiveSidebarItem(subItem, activePath));
 
+/**
+ * Checks if a sidebar item should be active, based on the active path.
+ */
 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);
+    return isActive(item.href, activePath);
   }
 
   if (item.type === 'category') {
     return (
-      isActive(item.href) || containsActiveSidebarItem(item.items, activePath)
+      isActive(item.href, activePath) ||
+      containsActiveSidebarItem(item.items, activePath)
     );
   }
 
   return false;
 }
 
-export function getBreadcrumbs({
-  sidebar,
-  pathname,
-}: {
-  sidebar: PropSidebar;
-  pathname: string;
-}): PropSidebarBreadcrumbsItem[] {
+/**
+ * Gets the breadcrumbs of the current doc page, based on its sidebar location.
+ * Returns `null` if there's no sidebar or breadcrumbs are disabled.
+ */
+export function useSidebarBreadcrumbs(): PropSidebarBreadcrumbsItem[] | null {
+  const sidebar = useDocsSidebar();
+  const {pathname} = useLocation();
+  const breadcrumbsOption = useActivePlugin()?.pluginData.breadcrumbs;
+
+  if (breadcrumbsOption === false || !sidebar) {
+    return null;
+  }
+
   const breadcrumbs: PropSidebarBreadcrumbsItem[] = [];
 
   function extract(items: PropSidebar) {
     for (const item of items) {
       if (
-        item.type === 'category' &&
-        (isSamePath(item.href, pathname) || extract(item.items))
+        (item.type === 'category' &&
+          (isSamePath(item.href, pathname) || extract(item.items))) ||
+        (item.type === 'link' && isSamePath(item.href, pathname))
       ) {
         breadcrumbs.push(item);
         return true;
-      } else if (item.type === 'link' && isSamePath(item.href, pathname)) {
-        breadcrumbs.push(item);
-        return true;
       }
     }
 
@@ -217,15 +178,3 @@ export function getBreadcrumbs({
 
   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/footerUtils.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 type {MultiColumnFooter, SimpleFooter} from './useThemeConfig';
+
+/**
+ * A rough duck-typing about whether the `footer.links` is intended to be multi-
+ * column.
+ */
+export function isMultiColumnFooterLinks(
+  links: MultiColumnFooter['links'] | SimpleFooter['links'],
+): links is MultiColumnFooter['links'] {
+  return 'title' in links[0]!;
+}

package/src/utils/generalUtils.ts

@@ -7,10 +7,13 @@
 
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
-export const useTitleFormatter = (title?: string | undefined): string => {
+/**
+ * Formats the page's title based on relevant site config and other contexts.
+ */
+export function useTitleFormatter(title?: string | undefined): string {
   const {siteConfig} = useDocusaurusContext();
   const {title: siteTitle, titleDelimiter} = siteConfig;
-  return title && title.trim().length
+  return title?.trim().length
     ? `${title.trim()} ${titleDelimiter} ${siteTitle}`
     : siteTitle;
-};
+}

package/src/utils/historyUtils.ts

@@ -5,44 +5,38 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useEffect, useRef} from 'react';
+import {useEffect} from 'react';
 import {useHistory} from '@docusaurus/router';
+import {useDynamicCallback} from './reactUtils';
 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
+ * push, replace). If the handler returns `false`, the navigation transition
+ * will be blocked/cancelled.
  */
-export function useHistoryActionHandler(handler: HistoryBlockHandler): void {
+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]);
-
+  const stableHandler = useDynamicCallback(handler);
   useEffect(
-    () =>
-      // See https://github.com/remix-run/history/blob/main/docs/blocking-transitions.md
-      block((location, action) => lastHandlerRef.current(location, action)),
-    [block, lastHandlerRef],
+    // See https://github.com/remix-run/history/blob/main/docs/blocking-transitions.md
+    () => block((location, action) => stableHandler(location, action)),
+    [block, stableHandler],
   );
 }
 
 /**
  * Permits to register a handler that will be called on history pop navigation
- * (backward/forward) If the handler returns false, the backward/forward
+ * (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
+      // Maybe block navigation if handler returns false
       return handler(location, action);
     }
     // Don't block other navigation actions

package/src/utils/jsUtils.ts

@@ -26,7 +26,7 @@ export function duplicates<T>(
 }
 
 /**
- * Remove duplicate array items (similar to _.uniq)
+ * Remove duplicate array items (similar to `_.uniq`)
  * @param arr The array.
  * @returns An array with duplicate elements removed by reference comparison.
  */

package/src/utils/metadataUtils.tsx

@@ -0,0 +1,115 @@
+/**
+ * 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, {type ReactNode} from 'react';
+import Head from '@docusaurus/Head';
+import clsx from 'clsx';
+import useRouteContext from '@docusaurus/useRouteContext';
+import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
+import {useTitleFormatter} from './generalUtils';
+
+interface PageMetadataProps {
+  readonly title?: string;
+  readonly description?: string;
+  readonly keywords?: readonly string[] | string;
+  readonly image?: string;
+  readonly children?: ReactNode;
+}
+
+/**
+ * Helper component to manipulate page metadata and override site defaults.
+ * Works in the same way as Helmet.
+ */
+export function PageMetadata({
+  title,
+  description,
+  keywords,
+  image,
+  children,
+}: PageMetadataProps): JSX.Element {
+  const pageTitle = useTitleFormatter(title);
+  const {withBaseUrl} = useBaseUrlUtils();
+  const pageImage = image ? withBaseUrl(image, {absolute: true}) : undefined;
+
+  return (
+    <Head>
+      {title && <title>{pageTitle}</title>}
+      {title && <meta property="og:title" content={pageTitle} />}
+
+      {description && <meta name="description" content={description} />}
+      {description && <meta property="og:description" content={description} />}
+
+      {keywords && (
+        <meta
+          name="keywords"
+          content={
+            // https://github.com/microsoft/TypeScript/issues/17002
+            (Array.isArray(keywords) ? keywords.join(',') : keywords) as string
+          }
+        />
+      )}
+
+      {pageImage && <meta property="og:image" content={pageImage} />}
+      {pageImage && <meta name="twitter:image" content={pageImage} />}
+
+      {children}
+    </Head>
+  );
+}
+
+const HtmlClassNameContext = React.createContext<string | undefined>(undefined);
+
+/**
+ * Every layer of this provider will append a class name to the HTML element.
+ * There's no consumer for this hook: it's side-effect-only. This wrapper is
+ * necessary because Helmet does not "merge" classes.
+ * @see https://github.com/staylor/react-helmet-async/issues/161
+ */
+export function HtmlClassNameProvider({
+  className: classNameProp,
+  children,
+}: {
+  className: string;
+  children: ReactNode;
+}): JSX.Element {
+  const classNameContext = React.useContext(HtmlClassNameContext);
+  const className = clsx(classNameContext, classNameProp);
+  return (
+    <HtmlClassNameContext.Provider value={className}>
+      <Head>
+        <html className={className} />
+      </Head>
+      {children}
+    </HtmlClassNameContext.Provider>
+  );
+}
+
+function pluginNameToClassName(pluginName: string) {
+  return `plugin-${pluginName.replace(
+    /docusaurus-(?:plugin|theme)-(?:content-)?/gi,
+    '',
+  )}`;
+}
+
+/**
+ * A very thin wrapper around `HtmlClassNameProvider` that adds the plugin ID +
+ * name to the HTML class name.
+ */
+export function PluginHtmlClassNameProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const routeContext = useRouteContext();
+  const nameClass = pluginNameToClassName(routeContext.plugin.name);
+  const idClass = `plugin-id-${routeContext.plugin.id}`;
+  return (
+    <HtmlClassNameProvider className={clsx(nameClass, idClass)}>
+      {children}
+    </HtmlClassNameProvider>
+  );
+}

package/src/utils/navbarUtils.tsx

@@ -0,0 +1,40 @@
+/**
+ * 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, {type ReactNode} from 'react';
+import {NavbarMobileSidebarProvider} from '../contexts/navbarMobileSidebar';
+import {NavbarSecondaryMenuProvider} from '../contexts/navbarSecondaryMenu';
+
+const DefaultNavItemPosition = 'right';
+
+/**
+ * Split links by left/right. If position is unspecified, fallback to right.
+ */
+export function splitNavbarItems<T extends {position?: 'left' | 'right'}>(
+  items: T[],
+): [leftItems: T[], rightItems: T[]] {
+  function isLeft(item: T): boolean {
+    return (item.position ?? DefaultNavItemPosition) === 'left';
+  }
+
+  const leftItems = items.filter(isLeft);
+  const rightItems = items.filter((item) => !isLeft(item));
+
+  return [leftItems, rightItems];
+}
+
+/**
+ * Composes the `NavbarMobileSidebarProvider` and `NavbarSecondaryMenuProvider`.
+ * Because the latter depends on the former, they can't be re-ordered.
+ */
+export function NavbarProvider({children}: {children: ReactNode}): JSX.Element {
+  return (
+    <NavbarMobileSidebarProvider>
+      <NavbarSecondaryMenuProvider>{children}</NavbarSecondaryMenuProvider>
+    </NavbarMobileSidebarProvider>
+  );
+}

package/src/utils/reactUtils.tsx

@@ -6,25 +6,29 @@
  */
 
 import {useCallback, useEffect, useLayoutEffect, useRef} 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...)
+ * 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`)
+ * render (before `useEffect`).
  */
-export const useIsomorphicLayoutEffect =
-  typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+export const useIsomorphicLayoutEffect = ExecutionEnvironment.canUseDOM
+  ? 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
+ * 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
+ * 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
  */
@@ -42,12 +46,31 @@ export function useDynamicCallback<T extends (...args: never[]) => unknown>(
   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 (?<name>\w+)/)?.groups!.name
+      this.stack?.split('\n')[1]?.match(/at (?:\w+\.)?(?<name>\w+)/)?.groups!
+        .name
     } is called outside the <${providerName}>. ${additionalInfo || ''}`;
   }
 }

package/src/utils/regexpUtils.ts

@@ -6,7 +6,8 @@
  */
 
 /**
- * Converts an optional string into a Regex case insensitive and global
+ * 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,

package/src/utils/routesUtils.ts

@@ -5,12 +5,31 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import GeneratedRoutes, {type Route} from '@generated/routes';
 import {useMemo} from 'react';
+import generatedRoutes from '@generated/routes';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import type {Route} from '@docusaurus/types';
 
-// Note that all sites don't always have a homepage in practice
-// See https://github.com/facebook/docusaurus/pull/6517#issuecomment-1048709116
+/**
+ * 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,
@@ -43,14 +62,14 @@ export function findHomePageRoute({
   return doFindHomePageRoute(initialRoutes);
 }
 
+/**
+ * Fetches the route that points to "/". Use this instead of the naive "/",
+ * because the homepage may not exist.
+ */
 export function useHomePageRoute(): Route | undefined {
   const {baseUrl} = useDocusaurusContext().siteConfig;
   return useMemo(
-    () =>
-      findHomePageRoute({
-        routes: GeneratedRoutes,
-        baseUrl,
-      }),
+    () => findHomePageRoute({routes: generatedRoutes, baseUrl}),
     [baseUrl],
   );
 }