chore: backport retro compatible commits for the Docusaurus v2.4 release (#8809)

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>
Co-authored-by: Ben Gubler <nebrelbug@gmail.com>
Co-authored-by: Davide Donadio <davide.donadio@it.clara.net>
Co-authored-by: Petter Drønnen <36735557+dr0nn1@users.noreply.github.com>
Co-authored-by: Moritz Stückler <moritz@bitbetter.de>
Co-authored-by: Mysterious_Dev <40738104+Mysterious-Dev@users.noreply.github.com>
Co-authored-by: TrueQAP <32407751+trueqap@users.noreply.github.com>
Co-authored-by: Kagan <34136752+kagankan@users.noreply.github.com>
Co-authored-by: Dewansh Thakur <71703033+dewanshDT@users.noreply.github.com>
Co-authored-by: Armano <armano2@users.noreply.github.com>
Co-authored-by: Anas <60762285+Anasqx@users.noreply.github.com>
Co-authored-by: Tanner Dolby <tannercdolby@gmail.com>
Co-authored-by: Davide Donadio <davide.donadio94@gmail.com>
Co-authored-by: biplavmz <68702055+biplavmz@users.noreply.github.com>
Co-authored-by: Vishruta Patil <72292532+Vishruta-Patil@users.noreply.github.com>
fix(theme-classic): fix tab focus bug in dropdown (#8697) (#8699)
fix(theme): improve color toggle when using dark navbar (#8615)
fix(theme-translations): fix wrong arabic words (tip/next) (#8744)
fix(core): baseUrl error banner link anchor case (#8746)
fix(search): search page should react to querystring changes + cleanup/refactor (#8757)
fix(theme): allow tabs children to be falsy (#8801)
fix(theme): codeblock buttons should be kept on the right when using RTL locale (#8803)

packages/docusaurus-theme-common/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-common",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Common code for Docusaurus themes.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -30,12 +30,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/mdx-loader": "2.3.1",
-    "@docusaurus/module-type-aliases": "2.3.1",
-    "@docusaurus/plugin-content-blog": "2.3.1",
-    "@docusaurus/plugin-content-docs": "2.3.1",
-    "@docusaurus/plugin-content-pages": "2.3.1",
-    "@docusaurus/utils": "2.3.1",
+    "@docusaurus/mdx-loader": "2.4.0",
+    "@docusaurus/module-type-aliases": "2.4.0",
+    "@docusaurus/plugin-content-blog": "2.4.0",
+    "@docusaurus/plugin-content-docs": "2.4.0",
+    "@docusaurus/plugin-content-pages": "2.4.0",
+    "@docusaurus/utils": "2.4.0",
+    "@docusaurus/utils-common": "2.4.0",
     "@types/history": "^4.7.11",
     "@types/react": "*",
     "@types/react-router-config": "*",
@@ -47,8 +48,8 @@
     "utility-types": "^3.10.0"
   },
   "devDependencies": {
-    "@docusaurus/core": "2.3.1",
-    "@docusaurus/types": "2.3.1",
+    "@docusaurus/core": "2.4.0",
+    "@docusaurus/types": "2.4.0",
     "fs-extra": "^10.1.0",
     "lodash": "^4.17.21"
   },

packages/docusaurus-theme-common/src/components/Collapsible/index.tsx

@@ -65,6 +65,10 @@ function applyCollapsedStyle(el: HTMLElement, collapsed: boolean) {
   el.style.height = collapsedStyles.height;
 }
 
+function userPrefersReducedMotion(): boolean {
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
 /*
 Lex111: Dynamic transition duration is used in Material design, this technique
 is good for a large number of items.
@@ -72,6 +76,9 @@ https://material.io/archive/guidelines/motion/duration-easing.html#duration-easi
 https://github.com/mui-org/material-ui/blob/e724d98eba018e55e1a684236a2037e24bcf050c/packages/material-ui/src/styles/createTransitions.js#L40-L43
  */
 function getAutoHeightDuration(height: number) {
+  if (userPrefersReducedMotion()) {
+    return 0;
+  }
   const constant = height / 36;
   return Math.round((4 + 15 * constant ** 0.25 + constant / 5) * 10);
 }

packages/docusaurus-theme-common/src/components/Details/index.tsx

@@ -31,8 +31,11 @@ function hasParent(node: HTMLElement | null, parent: HTMLElement): boolean {
 }
 
 export type DetailsProps = {
-  /** Summary is provided as props, including the wrapping `<summary>` tag */
-  summary?: ReactElement;
+  /**
+   * Summary is provided as props, optionally including the wrapping
+   * `<summary>` tag
+   */
+  summary?: ReactElement | string;
 } & ComponentProps<'details'>;
 
 /**
@@ -54,6 +57,12 @@ export function Details({
   // only after animation completes, otherwise close animations won't work
   const [open, setOpen] = useState(props.open);
 
+  const summaryElement = React.isValidElement(summary) ? (
+    summary
+  ) : (
+    <summary>{summary ?? 'Details'}</summary>
+  );
+
   return (
     // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-noninteractive-element-interactions
     <details
@@ -91,8 +100,7 @@ export function Details({
           // setOpen(false);
         }
       }}>
-      {/* eslint-disable-next-line @docusaurus/no-untranslated-text */}
-      {summary ?? <summary>Details</summary>}
+      {summaryElement}
 
       <Collapsible
         lazy={false} // Content might matter for SEO in this case

packages/docusaurus-theme-common/src/hooks/useSearchPage.ts

@@ -5,32 +5,24 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useCallback, useEffect, useState} from 'react';
-import {useHistory} from '@docusaurus/router';
+import {useCallback} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useQueryString} from '../utils/historyUtils';
 import type {ThemeConfig as AlgoliaThemeConfig} from '@docusaurus/theme-search-algolia';
 
 const SEARCH_PARAM_QUERY = 'q';
 
-/** Some utility functions around search queries. */
-export function useSearchPage(): {
-  /**
-   * Works hand-in-hand with `setSearchQuery`; whatever the user has inputted
-   * into the search box.
-   */
-  searchQuery: string;
-  /**
-   * Set a new search query. In addition to updating `searchQuery`, this handle
-   * also mutates the location and appends the query.
-   */
-  setSearchQuery: (newSearchQuery: string) => void;
-  /**
-   * Given a query, this handle generates the corresponding search page link,
-   * with base URL prepended.
-   */
-  generateSearchPageLink: (targetSearchQuery: string) => string;
-} {
-  const history = useHistory();
+/**
+ * Permits to read/write the current search query string
+ */
+export function useSearchQueryString(): [string, (newValue: string) => void] {
+  return useQueryString(SEARCH_PARAM_QUERY);
+}
+
+/**
+ * Permits to create links to the search page with the appropriate query string
+ */
+export function useSearchLinkCreator(): (searchValue: string) => string {
   const {
     siteConfig: {baseUrl, themeConfig},
   } = useDocusaurusContext();
@@ -38,47 +30,13 @@ export function useSearchPage(): {
     algolia: {searchPagePath},
   } = themeConfig as AlgoliaThemeConfig;
 
-  const [searchQuery, setSearchQueryState] = useState('');
-
-  // Init search query just after React hydration
-  useEffect(() => {
-    const searchQueryStringValue =
-      new URLSearchParams(window.location.search).get(SEARCH_PARAM_QUERY) ?? '';
-
-    setSearchQueryState(searchQueryStringValue);
-  }, []);
-
-  const setSearchQuery = useCallback(
-    (newSearchQuery: string) => {
-      const searchParams = new URLSearchParams(window.location.search);
-
-      if (newSearchQuery) {
-        searchParams.set(SEARCH_PARAM_QUERY, newSearchQuery);
-      } else {
-        searchParams.delete(SEARCH_PARAM_QUERY);
-      }
-
-      history.replace({
-        search: searchParams.toString(),
-      });
-      setSearchQueryState(newSearchQuery);
-    },
-    [history],
-  );
-
-  const generateSearchPageLink = useCallback(
-    (targetSearchQuery: string) =>
+  return useCallback(
+    (searchValue: string) =>
       // Refer to https://github.com/facebook/docusaurus/pull/2838
       // Note: if searchPagePath is falsy, useSearchPage() will not be called
       `${baseUrl}${
         searchPagePath as string
-      }?${SEARCH_PARAM_QUERY}=${encodeURIComponent(targetSearchQuery)}`,
+      }?${SEARCH_PARAM_QUERY}=${encodeURIComponent(searchValue)}`,
     [baseUrl, searchPagePath],
   );
-
-  return {
-    searchQuery,
-    setSearchQuery,
-    generateSearchPageLink,
-  };
 }

packages/docusaurus-theme-common/src/index.ts

@@ -73,6 +73,11 @@ export {
   type TagLetterEntry,
 } from './utils/tagsUtils';
 
+export {
+  useSearchQueryString,
+  useSearchLinkCreator,
+} from './hooks/useSearchPage';
+
 export {isMultiColumnFooterLinks} from './utils/footerUtils';
 
 export {isRegexpStringMatch} from './utils/regexpUtils';
@@ -89,3 +94,9 @@ export {
   SkipToContentFallbackId,
   SkipToContentLink,
 } from './utils/skipToContentUtils';
+
+export {
+  ErrorBoundaryTryAgainButton,
+  ErrorBoundaryError,
+  ErrorCauseBoundary,
+} from './utils/errorBoundaryUtils';

packages/docusaurus-theme-common/src/internal.ts

@@ -117,7 +117,6 @@ export {
   keyboardFocusedClassName,
 } from './hooks/useKeyboardNavigation';
 export {useLockBodyScroll} from './hooks/useLockBodyScroll';
-export {useSearchPage} from './hooks/useSearchPage';
 export {useCodeWordWrap} from './hooks/useCodeWordWrap';
 export {getPrismCssVariables} from './utils/codeBlockUtils';
 export {useBackToTopButton} from './hooks/useBackToTopButton';

packages/docusaurus-theme-common/src/utils/docsUtils.tsx

@@ -271,8 +271,8 @@ export function useLayoutDocsSidebar(
         `Can't find any sidebar with id "${sidebarId}" in version${
           versions.length > 1 ? 's' : ''
         } ${versions.map((version) => version.name).join(', ')}".
-  Available sidebar ids are:
-  - ${Object.keys(allSidebars).join('\n- ')}`,
+Available sidebar ids are:
+- ${Object.keys(allSidebars).join('\n- ')}`,
       );
     }
     return sidebarEntry[1];
@@ -304,9 +304,9 @@ export function useLayoutDoc(
         return null;
       }
       throw new Error(
-        `DocNavbarItem: couldn't find any doc with id "${docId}" in version${
+        `Couldn't find any doc with id "${docId}" in version${
           versions.length > 1 ? 's' : ''
-        } ${versions.map((version) => version.name).join(', ')}".
+        } "${versions.map((version) => version.name).join(', ')}".
 Available doc ids are:
 - ${uniq(allDocs.map((versionDoc) => versionDoc.id)).join('\n- ')}`,
       );

packages/docusaurus-theme-common/src/utils/errorBoundaryUtils.module.css

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+
+.errorBoundaryError {
+  white-space: pre-wrap;
+  color: red;
+}

packages/docusaurus-theme-common/src/utils/errorBoundaryUtils.tsx

@@ -0,0 +1,56 @@
+/**
+ * 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 ComponentProps} from 'react';
+import Translate from '@docusaurus/Translate';
+import {getErrorCausalChain} from '@docusaurus/utils-common';
+import styles from './errorBoundaryUtils.module.css';
+
+export function ErrorBoundaryTryAgainButton(
+  props: ComponentProps<'button'>,
+): JSX.Element {
+  return (
+    <button type="button" {...props}>
+      <Translate
+        id="theme.ErrorPageContent.tryAgain"
+        description="The label of the button to try again rendering when the React error boundary captures an error">
+        Try again
+      </Translate>
+    </button>
+  );
+}
+export function ErrorBoundaryError({error}: {error: Error}): JSX.Element {
+  const causalChain = getErrorCausalChain(error);
+  const fullMessage = causalChain.map((e) => e.message).join('\n\nCause:\n');
+  return <p className={styles.errorBoundaryError}>{fullMessage}</p>;
+}
+
+/**
+ * This component is useful to wrap a low-level error into a more meaningful
+ * error with extra context, using the ES error-cause feature.
+ *
+ * <ErrorCauseBoundary
+ *   onError={(error) => new Error("extra context message",{cause: error})}
+ * >
+ *   <RiskyComponent>
+ * </ErrorCauseBoundary>
+ */
+export class ErrorCauseBoundary extends React.Component<
+  {
+    children: React.ReactNode;
+    onError: (error: Error, errorInfo: React.ErrorInfo) => Error;
+  },
+  unknown
+> {
+  override componentDidCatch(error: Error, errorInfo: React.ErrorInfo): never {
+    throw this.props.onError(error, errorInfo);
+  }
+
+  override render(): React.ReactNode {
+    return this.props.children;
+  }
+}

packages/docusaurus-theme-common/src/utils/historyUtils.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useEffect} from 'react';
+import {useCallback, useEffect} from 'react';
 import {useHistory} from '@docusaurus/router';
 // @ts-expect-error: TODO temporary until React 18 upgrade
 import {useSyncExternalStore} from 'use-sync-external-store/shim';
@@ -75,3 +75,42 @@ export function useQueryStringValue(key: string | null): string | null {
     return new URLSearchParams(history.location.search).get(key);
   });
 }
+
+export function useQueryStringKeySetter(): (
+  key: string,
+  newValue: string | null,
+  options?: {push: boolean},
+) => void {
+  const history = useHistory();
+  return useCallback(
+    (key, newValue, options) => {
+      const searchParams = new URLSearchParams(history.location.search);
+      if (newValue) {
+        searchParams.set(key, newValue);
+      } else {
+        searchParams.delete(key);
+      }
+      const updaterFn = options?.push ? history.push : history.replace;
+      updaterFn({
+        search: searchParams.toString(),
+      });
+    },
+    [history],
+  );
+}
+
+export function useQueryString(
+  key: string,
+): [string, (newValue: string, options?: {push: boolean}) => void] {
+  const value = useQueryStringValue(key) ?? '';
+  const setQueryString = useQueryStringKeySetter();
+  return [
+    value,
+    useCallback(
+      (newValue: string, options) => {
+        setQueryString(key, newValue, options);
+      },
+      [setQueryString, key],
+    ),
+  ];
+}

packages/docusaurus-theme-common/src/utils/tabsUtils.tsx

@@ -29,12 +29,12 @@ export interface TabValue {
   readonly default?: boolean;
 }
 
+type TabItem = ReactElement<TabItemProps> | null | false | undefined;
+
 export interface TabsProps {
   readonly lazy?: boolean;
   readonly block?: boolean;
-  readonly children:
-    | readonly ReactElement<TabItemProps>[]
-    | ReactElement<TabItemProps>;
+  readonly children: TabItem[] | TabItem;
   readonly defaultValue?: string | null;
   readonly values?: readonly TabValue[];
   readonly groupId?: string;
@@ -55,14 +55,16 @@ export interface TabItemProps {
 // A very rough duck type, but good enough to guard against mistakes while
 // allowing customization
 function isTabItem(
-  comp: ReactElement<object>,
+  comp: ReactElement<unknown>,
 ): comp is ReactElement<TabItemProps> {
-  return 'value' in comp.props;
+  const {props} = comp;
+  return !!props && typeof props === 'object' && 'value' in props;
 }
 
 function ensureValidChildren(children: TabsProps['children']) {
-  return React.Children.map(children, (child) => {
-    if (isValidElement(child) && isTabItem(child)) {
+  return (React.Children.map(children, (child) => {
+    // Pass falsy values through: allow conditionally not rendering a tab
+    if (!child || (isValidElement(child) && isTabItem(child))) {
       return child;
     }
     // child.type.name will give non-sensical values in prod because of
@@ -73,7 +75,7 @@ function ensureValidChildren(children: TabsProps['children']) {
         typeof child.type === 'string' ? child.type : child.type.name
       }>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.`,
     );
-  });
+  })?.filter(Boolean) ?? []) as ReactElement<TabItemProps>[];
 }
 
 function extractChildrenTabValues(children: TabsProps['children']): TabValue[] {