chore: backport retro compatible commits for the Docusaurus v2.2 release (#8264)

Co-authored-by: Jan Peer Stoecklmair <jan.peer.stoecklmair@dynatrace.com>
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: LittleboyHarry <littleboyharry@qq.com>
Co-authored-by: Mikey O'Toole <mikey@homotechsual.dev>
Co-authored-by: Jan Peer Stöcklmair <jan.oster94@gmail.com>
Co-authored-by: Nguyễn Thành Nam <namnguyenthanh.work@gmail.com>
Co-authored-by: Sanjaiyan Parthipan <parthipankalayini@gmail.com>
Co-authored-by: Ramazan SANCAR <ramazansancar4545@gmail.com>
Co-authored-by: mturoci <64769322+mturoci@users.noreply.github.com>
Co-authored-by: Adnan Hashmi <56730784+adnanhashmi09@users.noreply.github.com>
Co-authored-by: Pranav Joglekar <pranav2000joglekar@gmail.com>
Co-authored-by: forgeRW <20483211+forgeRW@users.noreply.github.com>
Co-authored-by: Masahiko Hara <pasora@sfc.wide.ad.jp>
Co-authored-by: Johan Fagerberg <johanringmann@gmail.com>
Co-authored-by: John Reilly <johnny_reilly@hotmail.com>
Co-authored-by: Sam Wall <oss@samuelwall.co.uk>
Co-authored-by: Jeferson S. Brito <30840709+jeferson-sb@users.noreply.github.com>
Co-authored-by: evan <evanmccarthy@outlook.com>
Co-authored-by: Xabier Lahuerta Vazquez <xlahuerta@protonmail.com>
Co-authored-by: Forresst <forresst17@gmail.com>
Co-authored-by: Shanmughapriyan S <priyanshan03@gmail.com>
Co-authored-by: Alexey Pyltsyn <lex61rus@gmail.com>

packages/docusaurus-theme-common/package.json

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

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

@@ -62,7 +62,13 @@ export function useHideableNavbar(hideOnScroll: boolean): {
       return;
     }
 
-    if (locationChangeEvent.location.hash) {
+    // See https://github.com/facebook/docusaurus/pull/8059#issuecomment-1239639480
+    const currentHash = locationChangeEvent.location.hash;
+    const currentHashAnchor = currentHash
+      ? document.getElementById(currentHash.substring(1))
+      : undefined;
+
+    if (currentHashAnchor) {
       isFocusedAnchor.current = true;
       setIsNavbarVisible(false);
       return;

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

@@ -1,58 +0,0 @@
-/**
- * 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 React from 'react';
-import {useCallback, useRef} from 'react';
-import {useHistory} from '@docusaurus/router';
-import {useLocationChange} from '../utils/useLocationChange';
-import {ThemeClassNames} from '../utils/ThemeClassNames';
-
-function programmaticFocus(el: HTMLElement) {
-  el.setAttribute('tabindex', '-1');
-  el.focus();
-  el.removeAttribute('tabindex');
-}
-
-/** This hook wires the logic for a skip-to-content link. */
-export function useSkipToContent(): {
-  /**
-   * The ref to the container. On page transition, the container will be focused
-   * so that keyboard navigators can instantly interact with the link and jump
-   * to content. **Note:** the type is `RefObject<HTMLDivElement>` only because
-   * the typing for refs don't reflect that the `ref` prop is contravariant, so
-   * using `HTMLElement` causes type-checking to fail. You can plug the ref into
-   * any HTML element, as long as it can be focused.
-   */
-  containerRef: React.RefObject<HTMLDivElement>;
-  /**
-   * Callback fired when the skip to content link has been interacted with. It
-   * will programmatically focus the main content.
-   */
-  handleSkip: (e: React.MouseEvent<HTMLAnchorElement>) => void;
-} {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const {action} = useHistory();
-  const handleSkip = useCallback((e: React.MouseEvent<HTMLAnchorElement>) => {
-    e.preventDefault();
-
-    const targetElement: HTMLElement | null =
-      document.querySelector('main:first-of-type') ??
-      document.querySelector(`.${ThemeClassNames.wrapper.main}`);
-
-    if (targetElement) {
-      programmaticFocus(targetElement);
-    }
-  }, []);
-
-  useLocationChange(({location}) => {
-    if (containerRef.current && !location.hash && action === 'PUSH') {
-      programmaticFocus(containerRef.current);
-    }
-  });
-
-  return {containerRef, handleSkip};
-}

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

@@ -78,3 +78,10 @@ export {duplicates, uniq} from './utils/jsUtils';
 export {usePrismTheme} from './hooks/usePrismTheme';
 
 export {useDocsPreferredVersion} from './contexts/docsPreferredVersion';
+
+export {processAdmonitionProps} from './utils/admonitionUtils';
+
+export {
+  SkipToContentFallbackId,
+  SkipToContentLink,
+} from './utils/skipToContentUtils';

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

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

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

@@ -0,0 +1,43 @@
+/**
+ * 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';
+
+// Workaround because it's difficult in MDX v1 to provide a MDX title as props
+// See https://github.com/facebook/docusaurus/pull/7152#issuecomment-1145779682
+function extractMDXAdmonitionTitle(children: ReactNode): {
+  mdxAdmonitionTitle: ReactNode | undefined;
+  rest: ReactNode;
+} {
+  const items = React.Children.toArray(children);
+  const mdxAdmonitionTitle = items.find(
+    (item) =>
+      React.isValidElement(item) &&
+      (item.props as {mdxType: string} | null)?.mdxType ===
+        'mdxAdmonitionTitle',
+  ) as JSX.Element | undefined;
+  const rest = <>{items.filter((item) => item !== mdxAdmonitionTitle)}</>;
+  return {
+    mdxAdmonitionTitle: mdxAdmonitionTitle?.props.children,
+    rest,
+  };
+}
+
+export function processAdmonitionProps<
+  Props extends {readonly children: ReactNode; readonly title?: ReactNode},
+>(props: Props): Props {
+  const {mdxAdmonitionTitle, rest} = extractMDXAdmonitionTitle(props.children);
+  const title = props.title ?? mdxAdmonitionTitle;
+  return {
+    ...props,
+    // Do not return "title: undefined" prop
+    // this might create unwanted props overrides when merging props
+    // For example: {...default,...props}
+    ...(title && {title}),
+    children: rest,
+  };
+}

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

@@ -0,0 +1,103 @@
+/**
+ * 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, {useCallback, useRef, type ComponentProps} from 'react';
+import {useHistory} from '@docusaurus/router';
+import {translate} from '@docusaurus/Translate';
+import {useLocationChange} from './useLocationChange';
+
+/**
+ * The id of the element that should become focused on a page
+ * that does not have a <main> html tag.
+ * Focusing the Docusaurus Layout children is a reasonable fallback.
+ */
+export const SkipToContentFallbackId = 'docusaurus_skipToContent_fallback';
+
+/**
+ * Returns the skip to content element to focus when the link is clicked.
+ */
+function getSkipToContentTarget(): HTMLElement | null {
+  return (
+    // Try to focus the <main> in priority
+    // Note: this will only work if JS is enabled
+    // See https://github.com/facebook/docusaurus/issues/6411#issuecomment-1284136069
+    document.querySelector('main:first-of-type') ??
+    // Then try to focus the fallback element (usually the Layout children)
+    document.getElementById(SkipToContentFallbackId)
+  );
+}
+
+function programmaticFocus(el: HTMLElement) {
+  el.setAttribute('tabindex', '-1');
+  el.focus();
+  el.removeAttribute('tabindex');
+}
+
+/** This hook wires the logic for a skip-to-content link. */
+function useSkipToContent(): {
+  /**
+   * The ref to the container. On page transition, the container will be focused
+   * so that keyboard navigators can instantly interact with the link and jump
+   * to content.
+   */
+  containerRef: React.RefObject<HTMLDivElement>;
+  /**
+   * Callback fired when the skip to content link has been clicked.
+   * It will programmatically focus the main content.
+   */
+  onClick: (e: React.MouseEvent<HTMLAnchorElement>) => void;
+} {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const {action} = useHistory();
+
+  const onClick = useCallback((e: React.MouseEvent<HTMLAnchorElement>) => {
+    e.preventDefault();
+    const targetElement = getSkipToContentTarget();
+    if (targetElement) {
+      programmaticFocus(targetElement);
+    }
+  }, []);
+
+  // "Reset" focus when navigating.
+  // See https://github.com/facebook/docusaurus/pull/8204#issuecomment-1276547558
+  useLocationChange(({location}) => {
+    if (containerRef.current && !location.hash && action === 'PUSH') {
+      programmaticFocus(containerRef.current);
+    }
+  });
+
+  return {containerRef, onClick};
+}
+
+const DefaultSkipToContentLabel = translate({
+  id: 'theme.common.skipToMainContent',
+  description:
+    'The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation',
+  message: 'Skip to main content',
+});
+
+type SkipToContentLinkProps = Omit<ComponentProps<'a'>, 'href' | 'onClick'>;
+
+export function SkipToContentLink(props: SkipToContentLinkProps): JSX.Element {
+  const linkLabel = props.children ?? DefaultSkipToContentLabel;
+  const {containerRef, onClick} = useSkipToContent();
+  return (
+    <div
+      ref={containerRef}
+      role="region"
+      aria-label={DefaultSkipToContentLabel}>
+      <a
+        {...props}
+        // Note this is a fallback href in case JS is disabled
+        // It has limitations, see https://github.com/facebook/docusaurus/issues/6411#issuecomment-1284136069
+        href={`#${SkipToContentFallbackId}`}
+        onClick={onClick}>
+        {linkLabel}
+      </a>
+    </div>
+  );
+}