@docusaurus/theme-classic 2.1.0 → 2.3.0

package/src/theme/Heading/index.tsx

@@ -9,6 +9,7 @@ import React from 'react';
 import clsx from 'clsx';
 import {translate} from '@docusaurus/Translate';
 import {useThemeConfig} from '@docusaurus/theme-common';
+import Link from '@docusaurus/Link';
 import type {Props} from '@theme/Heading';
 
 import styles from './styles.module.css';
@@ -22,6 +23,17 @@ export default function Heading({as: As, id, ...props}: Props): JSX.Element {
     return <As {...props} id={undefined} />;
   }
 
+  const anchorTitle = translate(
+    {
+      id: 'theme.common.headingLinkTitle',
+      message: 'Direct link to {heading}',
+      description: 'Title for link to heading',
+    },
+    {
+      heading: typeof props.children === 'string' ? props.children : id,
+    },
+  );
+
   return (
     <As
       {...props}
@@ -30,19 +42,17 @@ export default function Heading({as: As, id, ...props}: Props): JSX.Element {
         hideOnScroll
           ? styles.anchorWithHideOnScrollNavbar
           : styles.anchorWithStickyNavbar,
+        props.className,
       )}
       id={id}>
       {props.children}
-      <a
+      <Link
         className="hash-link"
-        href={`#${id}`}
-        title={translate({
-          id: 'theme.common.headingLinkTitle',
-          message: 'Direct link to heading',
-          description: 'Title for link to heading',
-        })}>
+        to={`#${id}`}
+        aria-label={anchorTitle}
+        title={anchorTitle}>
         &#8203;
-      </a>
+      </Link>
     </As>
   );
 }

package/src/theme/Layout/Provider/index.tsx

@@ -9,7 +9,6 @@ import React from 'react';
 import {composeProviders} from '@docusaurus/theme-common';
 import {
   ColorModeProvider,
-  TabGroupChoiceProvider,
   AnnouncementBarProvider,
   DocsPreferredVersionContextProvider,
   ScrollControllerProvider,
@@ -21,7 +20,6 @@ import type {Props} from '@theme/Layout/Provider';
 const Provider = composeProviders([
   ColorModeProvider,
   AnnouncementBarProvider,
-  TabGroupChoiceProvider,
   ScrollControllerProvider,
   DocsPreferredVersionContextProvider,
   PluginHtmlClassNameProvider,

package/src/theme/Layout/index.tsx

@@ -8,7 +8,11 @@
 import React from 'react';
 import clsx from 'clsx';
 import ErrorBoundary from '@docusaurus/ErrorBoundary';
-import {PageMetadata, ThemeClassNames} from '@docusaurus/theme-common';
+import {
+  PageMetadata,
+  SkipToContentFallbackId,
+  ThemeClassNames,
+} from '@docusaurus/theme-common';
 import {useKeyboardNavigation} from '@docusaurus/theme-common/internal';
 import SkipToContent from '@theme/SkipToContent';
 import AnnouncementBar from '@theme/AnnouncementBar';
@@ -42,6 +46,7 @@ export default function Layout(props: Props): JSX.Element {
       <Navbar />
 
       <div
+        id={SkipToContentFallbackId}
         className={clsx(
           ThemeClassNames.wrapper.main,
           styles.mainWrapper,

package/src/theme/Layout/styles.module.css

@@ -12,6 +12,8 @@ body {
 
 .mainWrapper {
   flex: 1 0 auto;
+  display: flex;
+  flex-direction: column;
 }
 
 /* Docusaurus-specific utility class */

package/src/theme/MDXComponents/Code.tsx

@@ -13,15 +13,35 @@ import type {Props} from '@theme/MDXComponents/Code';
 export default function MDXCode(props: Props): JSX.Element {
   const inlineElements: (string | undefined)[] = [
     'a',
+    'abbr',
     'b',
-    'big',
+    'br',
+    'button',
+    'cite',
+    'code',
+    'del',
+    'dfn',
+    'em',
     'i',
+    'img',
+    'input',
+    'ins',
+    'kbd',
+    'label',
+    'object',
+    'output',
+    'q',
+    'ruby',
+    's',
+    'small',
     'span',
-    'em',
     'strong',
-    'sup',
     'sub',
-    'small',
+    'sup',
+    'time',
+    'u',
+    'var',
+    'wbr',
   ];
   const shouldBeInline = React.Children.toArray(props.children).every(
     (el) =>

package/src/theme/MDXComponents/index.tsx

@@ -15,6 +15,7 @@ import MDXHeading from '@theme/MDXComponents/Heading';
 import MDXUl from '@theme/MDXComponents/Ul';
 import MDXImg from '@theme/MDXComponents/Img';
 import Admonition from '@theme/Admonition';
+import Mermaid from '@theme/Mermaid';
 
 import type {MDXComponentsObject} from '@theme/MDXComponents';
 
@@ -33,6 +34,7 @@ const MDXComponents: MDXComponentsObject = {
   h5: (props) => <MDXHeading as="h5" {...props} />,
   h6: (props) => <MDXHeading as="h6" {...props} />,
   admonition: Admonition,
+  mermaid: Mermaid,
 };
 
 export default MDXComponents;

package/src/theme/Mermaid.tsx

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+
+// This component is meant to be implemented by a Mermaid renderer theme
+// It is notable created to be overridden by docusaurus-theme-mermaid
+
+// By default, the classic theme does not provide any Mermaid implementation
+// Yet we declare it there so that we can register it in MDX
+// TODO later the mermaid theme should be able to register its MDX component
+// see https://github.com/facebook/docusaurus/pull/7490#issuecomment-1279117288
+
+export {default} from '@docusaurus/Noop';

package/src/theme/Navbar/Layout/index.tsx

@@ -12,6 +12,7 @@ import {
   useHideableNavbar,
   useNavbarMobileSidebar,
 } from '@docusaurus/theme-common/internal';
+import {translate} from '@docusaurus/Translate';
 import NavbarMobileSidebar from '@theme/Navbar/MobileSidebar';
 import type {Props} from '@theme/Navbar/Layout';
 
@@ -36,6 +37,11 @@ export default function NavbarLayout({children}: Props): JSX.Element {
   return (
     <nav
       ref={navbarRef}
+      aria-label={translate({
+        id: 'theme.NavBar.navAriaLabel',
+        message: 'Main',
+        description: 'The ARIA label for the main navigation',
+      })}
       className={clsx(
         'navbar',
         'navbar--fixed-top',

package/src/theme/Navbar/MobileSidebar/Header/index.tsx

@@ -7,6 +7,7 @@
 
 import React from 'react';
 import {useNavbarMobileSidebar} from '@docusaurus/theme-common/internal';
+import {translate} from '@docusaurus/Translate';
 import NavbarColorModeToggle from '@theme/Navbar/ColorModeToggle';
 import IconClose from '@theme/Icon/Close';
 import NavbarLogo from '@theme/Navbar/Logo';
@@ -16,6 +17,11 @@ function CloseButton() {
   return (
     <button
       type="button"
+      aria-label={translate({
+        id: 'theme.docs.sidebar.closeSidebarButtonAriaLabel',
+        message: 'Close navigation bar',
+        description: 'The ARIA label for close button of mobile sidebar',
+      })}
       className="clean-btn navbar-sidebar__close"
       onClick={() => mobileSidebar.toggle()}>
       <IconClose color="var(--ifm-color-emphasis-600)" />

package/src/theme/Navbar/MobileSidebar/Toggle/index.tsx

@@ -7,18 +7,23 @@
 
 import React from 'react';
 import {useNavbarMobileSidebar} from '@docusaurus/theme-common/internal';
+import {translate} from '@docusaurus/Translate';
 import IconMenu from '@theme/Icon/Menu';
 
 export default function MobileSidebarToggle(): JSX.Element {
-  const mobileSidebar = useNavbarMobileSidebar();
+  const {toggle, shown} = useNavbarMobileSidebar();
   return (
     <button
-      onClick={mobileSidebar.toggle}
-      onKeyDown={mobileSidebar.toggle}
-      aria-label="Navigation bar toggle"
+      onClick={toggle}
+      aria-label={translate({
+        id: 'theme.docs.sidebar.toggleSidebarButtonAriaLabel',
+        message: 'Toggle navigation bar',
+        description:
+          'The ARIA label for hamburger menu button of mobile navigation',
+      })}
+      aria-expanded={shown}
       className="navbar__toggle clean-btn"
-      type="button"
-      tabIndex={0}>
+      type="button">
       <IconMenu />
     </button>
   );

package/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx

@@ -13,6 +13,7 @@ import {
 import {useDocsPreferredVersion} from '@docusaurus/theme-common';
 import {useDocsVersionCandidates} from '@docusaurus/theme-common/internal';
 import {translate} from '@docusaurus/Translate';
+import {useLocation} from '@docusaurus/router';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
 import type {Props} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
@@ -29,6 +30,7 @@ export default function DocsVersionDropdownNavbarItem({
   dropdownItemsAfter,
   ...props
 }: Props): JSX.Element {
+  const {search, hash} = useLocation();
   const activeDocContext = useActiveDocContext(docsPluginId);
   const versions = useVersions(docsPluginId);
   const {savePreferredVersionName} = useDocsPreferredVersion(docsPluginId);
@@ -40,7 +42,8 @@ export default function DocsVersionDropdownNavbarItem({
       getVersionMainDoc(version);
     return {
       label: version.label,
-      to: versionDoc.path,
+      // preserve ?search#hash suffix on version switches
+      to: `${versionDoc.path}${search}${hash}`,
       isActive: () => version === activeDocContext.activeVersion,
       onClick: () => savePreferredVersionName(version.name),
     };

package/src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx

@@ -9,6 +9,7 @@ import React from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {useAlternatePageUtils} from '@docusaurus/theme-common/internal';
 import {translate} from '@docusaurus/Translate';
+import {useLocation} from '@docusaurus/router';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
 import IconLanguage from '@theme/Icon/Language';
 import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
@@ -26,12 +27,15 @@ export default function LocaleDropdownNavbarItem({
     i18n: {currentLocale, locales, localeConfigs},
   } = useDocusaurusContext();
   const alternatePageUtils = useAlternatePageUtils();
+  const {search, hash} = useLocation();
 
   const localeItems = locales.map((locale): LinkLikeNavbarItemProps => {
-    const to = `pathname://${alternatePageUtils.createUrl({
+    const baseTo = `pathname://${alternatePageUtils.createUrl({
       locale,
       fullyQualified: false,
     })}`;
+    // preserve ?search#hash suffix on locale switches
+    const to = `${baseTo}${search}${hash}`;
     return {
       label: localeConfigs[locale]!.label,
       lang: localeConfigs[locale]!.htmlLang,

package/src/theme/SkipToContent/index.tsx

@@ -6,26 +6,10 @@
  */
 
 import React from 'react';
-import Translate, {translate} from '@docusaurus/Translate';
-import {useSkipToContent} from '@docusaurus/theme-common/internal';
+import {SkipToContentLink} from '@docusaurus/theme-common';
 
 import styles from './styles.module.css';
 
 export default function SkipToContent(): JSX.Element {
-  const {containerRef, handleSkip} = useSkipToContent();
-  return (
-    <div
-      ref={containerRef}
-      role="region"
-      aria-label={translate({id: 'theme.common.skipToMainContent'})}>
-      {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
-      <a href="#" className={styles.skipToContent} onClick={handleSkip}>
-        <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">
-          Skip to main content
-        </Translate>
-      </a>
-    </div>
-  );
+  return <SkipToContentLink className={styles.skipToContent} />;
 }

package/src/theme/Tabs/index.tsx

@@ -5,118 +5,40 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {
-  useState,
-  cloneElement,
-  isValidElement,
-  type ReactElement,
-} from 'react';
+import React, {cloneElement} from 'react';
 import clsx from 'clsx';
-import useIsBrowser from '@docusaurus/useIsBrowser';
-import {duplicates} from '@docusaurus/theme-common';
 import {
   useScrollPositionBlocker,
-  useTabGroupChoice,
+  useTabs,
 } from '@docusaurus/theme-common/internal';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 import type {Props} from '@theme/Tabs';
-import type {Props as TabItemProps} from '@theme/TabItem';
-
 import styles from './styles.module.css';
 
-// A very rough duck type, but good enough to guard against mistakes while
-// allowing customization
-function isTabItem(
-  comp: ReactElement<object>,
-): comp is ReactElement<TabItemProps> {
-  return 'value' in comp.props;
-}
-
-function TabsComponent(props: Props): JSX.Element {
-  const {
-    lazy,
-    block,
-    defaultValue: defaultValueProp,
-    values: valuesProp,
-    groupId,
-    className,
-  } = props;
-  const children = React.Children.map(props.children, (child) => {
-    if (isValidElement(child) && isTabItem(child)) {
-      return child;
-    }
-    // child.type.name will give non-sensical values in prod because of
-    // minification, but we assume it won't throw in prod.
-    throw new Error(
-      `Docusaurus error: Bad <Tabs> child <${
-        // @ts-expect-error: guarding against unexpected cases
-        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.`,
-    );
-  });
-  const values =
-    valuesProp ??
-    // Only pick keys that we recognize. MDX would inject some keys by default
-    children.map(({props: {value, label, attributes}}) => ({
-      value,
-      label,
-      attributes,
-    }));
-  const dup = duplicates(values, (a, b) => a.value === b.value);
-  if (dup.length > 0) {
-    throw new Error(
-      `Docusaurus error: Duplicate values "${dup
-        .map((a) => a.value)
-        .join(', ')}" found in <Tabs>. Every value needs to be unique.`,
-    );
-  }
-  // When defaultValueProp is null, don't show a default tab
-  const defaultValue =
-    defaultValueProp === null
-      ? defaultValueProp
-      : defaultValueProp ??
-        children.find((child) => child.props.default)?.props.value ??
-        children[0]!.props.value;
-  if (defaultValue !== null && !values.some((a) => a.value === defaultValue)) {
-    throw new Error(
-      `Docusaurus error: The <Tabs> has a defaultValue "${defaultValue}" but none of its children has the corresponding value. Available values are: ${values
-        .map((a) => a.value)
-        .join(
-          ', ',
-        )}. If you intend to show no default tab, use defaultValue={null} instead.`,
-    );
-  }
-
-  const {tabGroupChoices, setTabGroupChoices} = useTabGroupChoice();
-  const [selectedValue, setSelectedValue] = useState(defaultValue);
+function TabList({
+  className,
+  block,
+  selectedValue,
+  selectValue,
+  tabValues,
+}: Props & ReturnType<typeof useTabs>) {
   const tabRefs: (HTMLLIElement | null)[] = [];
   const {blockElementScrollPositionUntilNextRender} =
     useScrollPositionBlocker();
 
-  if (groupId != null) {
-    const relevantTabGroupChoice = tabGroupChoices[groupId];
-    if (
-      relevantTabGroupChoice != null &&
-      relevantTabGroupChoice !== selectedValue &&
-      values.some((value) => value.value === relevantTabGroupChoice)
-    ) {
-      setSelectedValue(relevantTabGroupChoice);
-    }
-  }
-
   const handleTabChange = (
-    event: React.FocusEvent<HTMLLIElement> | React.MouseEvent<HTMLLIElement>,
+    event:
+      | React.FocusEvent<HTMLLIElement>
+      | React.MouseEvent<HTMLLIElement>
+      | React.KeyboardEvent<HTMLLIElement>,
   ) => {
     const newTab = event.currentTarget;
     const newTabIndex = tabRefs.indexOf(newTab);
-    const newTabValue = values[newTabIndex]!.value;
+    const newTabValue = tabValues[newTabIndex]!.value;
 
     if (newTabValue !== selectedValue) {
       blockElementScrollPositionUntilNextRender(newTab);
-      setSelectedValue(newTabValue);
-
-      if (groupId != null) {
-        setTabGroupChoices(groupId, String(newTabValue));
-      }
+      selectValue(newTabValue);
     }
   };
 
@@ -124,6 +46,10 @@ function TabsComponent(props: Props): JSX.Element {
     let focusElement: HTMLLIElement | null = null;
 
     switch (event.key) {
+      case 'Enter': {
+        handleTabChange(event);
+        break;
+      }
       case 'ArrowRight': {
         const nextTab = tabRefs.indexOf(event.currentTarget) + 1;
         focusElement = tabRefs[nextTab] ?? tabRefs[0]!;
@@ -142,62 +68,79 @@ function TabsComponent(props: Props): JSX.Element {
   };
 
   return (
-    <div className={clsx('tabs-container', styles.tabList)}>
-      <ul
-        role="tablist"
-        aria-orientation="horizontal"
-        className={clsx(
-          'tabs',
-          {
-            'tabs--block': block,
-          },
-          className,
-        )}>
-        {values.map(({value, label, attributes}) => (
-          <li
-            role="tab"
-            tabIndex={selectedValue === value ? 0 : -1}
-            aria-selected={selectedValue === value}
-            key={value}
-            ref={(tabControl) => tabRefs.push(tabControl)}
-            onKeyDown={handleKeydown}
-            onFocus={handleTabChange}
-            onClick={handleTabChange}
-            {...attributes}
-            className={clsx(
-              'tabs__item',
-              styles.tabItem,
-              attributes?.className as string,
-              {
-                'tabs__item--active': selectedValue === value,
-              },
-            )}>
-            {label ?? value}
-          </li>
-        ))}
-      </ul>
+    <ul
+      role="tablist"
+      aria-orientation="horizontal"
+      className={clsx(
+        'tabs',
+        {
+          'tabs--block': block,
+        },
+        className,
+      )}>
+      {tabValues.map(({value, label, attributes}) => (
+        <li
+          // TODO extract TabListItem
+          role="tab"
+          tabIndex={selectedValue === value ? 0 : -1}
+          aria-selected={selectedValue === value}
+          key={value}
+          ref={(tabControl) => tabRefs.push(tabControl)}
+          onKeyDown={handleKeydown}
+          onClick={handleTabChange}
+          {...attributes}
+          className={clsx(
+            'tabs__item',
+            styles.tabItem,
+            attributes?.className as string,
+            {
+              'tabs__item--active': selectedValue === value,
+            },
+          )}>
+          {label ?? value}
+        </li>
+      ))}
+    </ul>
+  );
+}
 
-      {lazy ? (
-        cloneElement(
-          children.filter(
-            (tabItem) => tabItem.props.value === selectedValue,
-          )[0]!,
-          {className: 'margin-top--md'},
-        )
-      ) : (
-        <div className="margin-top--md">
-          {children.map((tabItem, i) =>
-            cloneElement(tabItem, {
-              key: i,
-              hidden: tabItem.props.value !== selectedValue,
-            }),
-          )}
-        </div>
+function TabContent({
+  lazy,
+  children,
+  selectedValue,
+}: Props & ReturnType<typeof useTabs>) {
+  if (lazy) {
+    const selectedTabItem = children.find(
+      (tabItem) => tabItem.props.value === selectedValue,
+    );
+    if (!selectedTabItem) {
+      // fail-safe or fail-fast? not sure what's best here
+      return null;
+    }
+    return cloneElement(selectedTabItem, {className: 'margin-top--md'});
+  }
+  return (
+    <div className="margin-top--md">
+      {children.map((tabItem, i) =>
+        cloneElement(tabItem, {
+          key: i,
+          hidden: tabItem.props.value !== selectedValue,
+        }),
       )}
     </div>
   );
 }
 
+function TabsComponent(props: Props): JSX.Element {
+  const tabs = useTabs(props);
+  return (
+    <div className={clsx('tabs-container', styles.tabList)}>
+      <TabList {...props} {...tabs} />
+      <TabContent {...props} {...tabs} />
+    </div>
+  );
+}
+
 export default function Tabs(props: Props): JSX.Element {
   const isBrowser = useIsBrowser();
   return (

package/src/theme/Tag/styles.module.css

@@ -20,7 +20,7 @@
 }
 
 .tagRegular {
-  border-radius: 0.5rem;
+  border-radius: var(--ifm-global-radius);
   padding: 0.2rem 0.5rem 0.3rem;
   font-size: 90%;
 }