@docusaurus/theme-classic 2.0.0-beta.14 → 2.0.0-beta.15

package/src/theme/DocSidebarItem/index.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useEffect, memo, useMemo} from 'react';
+import React, {useEffect, useMemo} from 'react';
 import clsx from 'clsx';
 import {
   isActiveSidebarItem,
@@ -14,13 +14,16 @@ import {
   useCollapsible,
   findFirstCategoryLink,
   ThemeClassNames,
+  useThemeConfig,
+  useDocSidebarItemsExpandedState,
 } from '@docusaurus/theme-common';
 import Link from '@docusaurus/Link';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import {translate} from '@docusaurus/Translate';
 import IconExternalLink from '@theme/IconExternalLink';
 
-import type {Props, DocSidebarItemsProps} from '@theme/DocSidebarItem';
+import DocSidebarItems from '@theme/DocSidebarItems';
+import type {Props} from '@theme/DocSidebarItem';
 import type {
   PropSidebarItemCategory,
   PropSidebarItemLink,
@@ -29,23 +32,6 @@ import type {
 import styles from './styles.module.css';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 
-// Optimize sidebar at each "level"
-// TODO this item should probably not receive the "activePath" props
-// TODO this triggers whole sidebar re-renders on navigation
-export const DocSidebarItems = memo(
-  ({items, ...props}: DocSidebarItemsProps): JSX.Element => (
-    <>
-      {items.map((item, index) => (
-        <DocSidebarItem
-          key={index} // sidebar is static, the index does not change
-          item={item}
-          {...props}
-        />
-      ))}
-    </>
-  ),
-);
-
 export default function DocSidebarItem({
   item,
   ...props
@@ -108,6 +94,7 @@ function DocSidebarItemCategory({
   onItemClick,
   activePath,
   level,
+  index,
   ...props
 }: Props & {item: PropSidebarItemCategory}) {
   const {items, label, collapsible, className, href} = item;
@@ -115,7 +102,7 @@ function DocSidebarItemCategory({
 
   const isActive = isActiveSidebarItem(item, activePath);
 
-  const {collapsed, setCollapsed, toggleCollapsed} = useCollapsible({
+  const {collapsed, setCollapsed} = useCollapsible({
     // active categories are always initialized as expanded
     // the default (item.collapsed) is only used for non-active categories
     initialState: () => {
@@ -127,6 +114,28 @@ function DocSidebarItemCategory({
   });
 
   useAutoExpandActiveCategory({isActive, collapsed, setCollapsed});
+  const {expandedItem, setExpandedItem} = useDocSidebarItemsExpandedState();
+  function updateCollapsed(toCollapsed: boolean = !collapsed) {
+    setExpandedItem(toCollapsed ? null : index);
+    setCollapsed(toCollapsed);
+  }
+  const {autoCollapseSidebarCategories} = useThemeConfig();
+  useEffect(() => {
+    if (
+      collapsible &&
+      expandedItem &&
+      expandedItem !== index &&
+      autoCollapseSidebarCategories
+    ) {
+      setCollapsed(true);
+    }
+  }, [
+    collapsible,
+    expandedItem,
+    index,
+    setCollapsed,
+    autoCollapseSidebarCategories,
+  ]);
 
   return (
     <li
@@ -152,16 +161,17 @@ function DocSidebarItemCategory({
               ? (e) => {
                   onItemClick?.(item);
                   if (href) {
-                    setCollapsed(false);
+                    updateCollapsed(false);
                   } else {
                     e.preventDefault();
-                    toggleCollapsed();
+                    updateCollapsed();
                   }
                 }
               : () => {
                   onItemClick?.(item);
                 }
           }
+          aria-current={isActive ? 'page' : undefined}
           href={collapsible ? hrefWithSSRFallback ?? '#' : hrefWithSSRFallback}
           {...props}>
           {label}
@@ -181,7 +191,7 @@ function DocSidebarItemCategory({
             className="clean-btn menu__caret"
             onClick={(e) => {
               e.preventDefault();
-              toggleCollapsed();
+              updateCollapsed();
             }}
           />
         )}
@@ -205,6 +215,7 @@ function DocSidebarItemLink({
   onItemClick,
   activePath,
   level,
+  index,
   ...props
 }: Props & {item: PropSidebarItemLink}) {
   const {href, label, className} = item;

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

@@ -9,6 +9,7 @@
   .menuLinkText {
     cursor: initial;
   }
+
   .menuLinkText:hover {
     background: none;
   }

package/src/theme/DocSidebarItems/index.tsx

@@ -0,0 +1,32 @@
+/**
+ * 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, {memo} from 'react';
+import DocSidebarItem from '@theme/DocSidebarItem';
+import {DocSidebarItemsExpandedStateProvider} from '@docusaurus/theme-common';
+
+import type {Props} from '@theme/DocSidebarItems';
+
+// TODO this item should probably not receive the "activePath" props
+// TODO this triggers whole sidebar re-renders on navigation
+function DocSidebarItems({items, ...props}: Props): JSX.Element {
+  return (
+    <DocSidebarItemsExpandedStateProvider>
+      {items.map((item, index) => (
+        <DocSidebarItem
+          key={index} // sidebar is static, the index does not change
+          item={item}
+          index={index}
+          {...props}
+        />
+      ))}
+    </DocSidebarItemsExpandedStateProvider>
+  );
+}
+
+// Optimize sidebar at each "level"
+export default memo(DocSidebarItems);

package/src/theme/{UserPreferencesContext.ts → DocSidebarItems/styles.module.css}

@@ -5,8 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {createContext} from 'react';
+@media (min-width: 997px) {
+  .menuLinkText {
+    cursor: initial;
+  }
 
-const UserPreferencesContext = createContext(undefined);
+  .menuLinkText:hover {
+    background: none;
+  }
 
-export default UserPreferencesContext;
+  .menuLinkText.hasHref {
+    cursor: pointer;
+  }
+}

package/src/theme/DocVersionBanner/index.tsx

@@ -5,15 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {ComponentType} from 'react';
+import React, {type ComponentType} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Link from '@docusaurus/Link';
 import Translate from '@docusaurus/Translate';
 import {
   useActivePlugin,
   useDocVersionSuggestions,
-  GlobalVersion,
-} from '@theme/hooks/useDocs';
+  type GlobalVersion,
+} from '@docusaurus/plugin-content-docs/client';
 import {
   ThemeClassNames,
   useDocsPreferredVersion,

package/src/theme/Footer/index.tsx

@@ -10,15 +10,15 @@ import clsx from 'clsx';
 
 import Link from '@docusaurus/Link';
 import {
-  FooterLinkItem,
+  type FooterLinkItem,
   useThemeConfig,
-  MultiColumnFooter,
-  SimpleFooter,
+  type MultiColumnFooter,
+  type SimpleFooter,
 } from '@docusaurus/theme-common';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import styles from './styles.module.css';
-import ThemedImage, {Props as ThemedImageProps} from '@theme/ThemedImage';
+import ThemedImage, {type Props as ThemedImageProps} from '@theme/ThemedImage';
 import IconExternalLink from '@theme/IconExternalLink';
 
 function FooterLink({

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

@@ -7,7 +7,8 @@
 
 .footerLogoLink {
   opacity: 0.5;
-  transition: opacity var(--ifm-transition-fast) var(--ifm-transition-timing-default);
+  transition: opacity var(--ifm-transition-fast)
+    var(--ifm-transition-timing-default);
 }
 
 .footerLogoLink:hover {

package/src/theme/Heading/index.tsx

@@ -7,62 +7,55 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import type {HeadingType, Props} from '@theme/Heading';
+import type {Props} from '@theme/Heading';
 import {translate} from '@docusaurus/Translate';
 import {useThemeConfig} from '@docusaurus/theme-common';
 
 import './styles.css';
 import styles from './styles.module.css';
 
-type HeadingComponent = (props: Props) => JSX.Element;
+function AnchorHeading({as: As, id, ...props}: Props) {
+  const {
+    navbar: {hideOnScroll},
+  } = useThemeConfig();
 
-// eslint-disable-next-line react/function-component-definition
-export const MainHeading: HeadingComponent = ({...props}) => (
-  <header>
-    <h1
+  if (!id) {
+    return <As {...props} />;
+  }
+
+  return (
+    <As
       {...props}
-      id={undefined} // h1 headings do not need an id because they don't appear in the TOC
-    >
+      className={clsx('anchor', {
+        [styles.anchorWithHideOnScrollNavbar]: hideOnScroll,
+        [styles.anchorWithStickyNavbar]: !hideOnScroll,
+      })}
+      id={id}>
       {props.children}
-    </h1>
-  </header>
-);
-
-const createAnchorHeading =
-  (Tag: HeadingType) =>
-  ({id, ...props}: Props) => {
-    const {
-      navbar: {hideOnScroll},
-    } = useThemeConfig();
-
-    if (!id) {
-      return <Tag {...props} />;
-    }
-
+      <a
+        className="hash-link"
+        href={`#${id}`}
+        title={translate({
+          id: 'theme.common.headingLinkTitle',
+          message: 'Direct link to heading',
+          description: 'Title for link to heading',
+        })}>
+        &#8203;
+      </a>
+    </As>
+  );
+}
+
+export default function Heading({as, ...props}: Props): JSX.Element {
+  if (as === 'h1') {
     return (
-      <Tag
+      <h1
         {...props}
-        className={clsx('anchor', {
-          [styles.anchorWithHideOnScrollNavbar]: hideOnScroll,
-          [styles.anchorWithStickyNavbar]: !hideOnScroll,
-        })}
-        id={id}>
+        id={undefined} // h1 headings do not need an id because they don't appear in the TOC
+      >
         {props.children}
-        <a
-          className="hash-link"
-          href={`#${id}`}
-          title={translate({
-            id: 'theme.common.headingLinkTitle',
-            message: 'Direct link to heading',
-            description: 'Title for link to heading',
-          })}>
-          &#8203;
-        </a>
-      </Tag>
+      </h1>
     );
-  };
-
-const Heading = (headingType: HeadingType): ((props: Props) => JSX.Element) =>
-  headingType === 'h1' ? MainHeading : createAnchorHeading(headingType);
-
-export default Heading;
+  }
+  return <AnchorHeading as={as} {...props} />;
+}

package/src/theme/Heading/styles.css

@@ -12,7 +12,7 @@
   user-select: none;
 }
 
-.hash-link:before {
+.hash-link::before {
   content: '#';
 }
 

package/src/theme/Layout/index.tsx

@@ -15,8 +15,7 @@ import Footer from '@theme/Footer';
 import LayoutProviders from '@theme/LayoutProviders';
 import LayoutHead from '@theme/LayoutHead';
 import type {Props} from '@theme/Layout';
-import useKeyboardNavigation from '@theme/hooks/useKeyboardNavigation';
-import {ThemeClassNames} from '@docusaurus/theme-common';
+import {ThemeClassNames, useKeyboardNavigation} from '@docusaurus/theme-common';
 import ErrorPageContent from '@theme/ErrorPageContent';
 import './styles.css';
 

package/src/theme/LayoutHead/index.tsx

@@ -25,7 +25,7 @@ import {useLocation} from '@docusaurus/router';
 // See https://github.com/facebook/docusaurus/issues/3317
 function AlternateLangHeaders(): JSX.Element {
   const {
-    i18n: {defaultLocale, locales},
+    i18n: {defaultLocale, localeConfigs},
   } = useDocusaurusContext();
   const alternatePageUtils = useAlternatePageUtils();
 
@@ -33,7 +33,7 @@ function AlternateLangHeaders(): JSX.Element {
   // See https://www.searchviu.com/en/multiple-hreflang-tags-one-url/
   return (
     <Head>
-      {locales.map((locale) => (
+      {Object.entries(localeConfigs).map(([locale, {htmlLang}]) => (
         <link
           key={locale}
           rel="alternate"
@@ -41,7 +41,7 @@ function AlternateLangHeaders(): JSX.Element {
             locale,
             fullyQualified: true,
           })}
-          hrefLang={locale}
+          hrefLang={htmlLang}
         />
       ))}
       <link
@@ -91,11 +91,7 @@ export default function LayoutHead(props: Props): JSX.Element {
   const {title, description, image, keywords, searchMetadata} = props;
   const faviconUrl = useBaseUrl(favicon);
   const pageTitle = useTitleFormatter(title);
-
-  // See https://github.com/facebook/docusaurus/issues/3317#issuecomment-754661855
-  // const htmlLang = currentLocale.split('-')[0];
-  const htmlLang = currentLocale; // should we allow the user to override htmlLang with localeConfig?
-  const htmlDir = localeConfigs[currentLocale].direction;
+  const {htmlLang, direction: htmlDir} = localeConfigs[currentLocale];
 
   return (
     <>

package/src/theme/LayoutProviders/index.tsx

@@ -6,9 +6,9 @@
  */
 
 import React from 'react';
-import ThemeProvider from '@theme/ThemeProvider';
-import UserPreferencesProvider from '@theme/UserPreferencesProvider';
 import {
+  ColorModeProvider,
+  TabGroupChoiceProvider,
   AnnouncementBarProvider,
   DocsPreferredVersionContextProvider,
   MobileSecondaryMenuProvider,
@@ -18,9 +18,9 @@ import type {Props} from '@theme/LayoutProviders';
 
 export default function LayoutProviders({children}: Props): JSX.Element {
   return (
-    <ThemeProvider>
+    <ColorModeProvider>
       <AnnouncementBarProvider>
-        <UserPreferencesProvider>
+        <TabGroupChoiceProvider>
           <ScrollControllerProvider>
             <DocsPreferredVersionContextProvider>
               <MobileSecondaryMenuProvider>
@@ -28,8 +28,8 @@ export default function LayoutProviders({children}: Props): JSX.Element {
               </MobileSecondaryMenuProvider>
             </DocsPreferredVersionContextProvider>
           </ScrollControllerProvider>
-        </UserPreferencesProvider>
+        </TabGroupChoiceProvider>
       </AnnouncementBarProvider>
-    </ThemeProvider>
+    </ColorModeProvider>
   );
 }

package/src/theme/MDXComponents/index.tsx

@@ -5,10 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {ComponentProps, isValidElement, ReactElement} from 'react';
+import React, {
+  type ComponentProps,
+  isValidElement,
+  type ReactElement,
+} from 'react';
 import Head from '@docusaurus/Head';
 import Link from '@docusaurus/Link';
-import CodeBlock, {Props} from '@theme/CodeBlock';
+import CodeBlock from '@theme/CodeBlock';
 import Heading from '@theme/Heading';
 import Details from '@theme/Details';
 import type {MDXComponentsObject} from '@theme/MDXComponents';
@@ -33,40 +37,25 @@ const MDXComponents: MDXComponentsObject = {
     return <Head {...props}>{unwrappedChildren}</Head>;
   },
   code: (props) => {
-    const {children} = props;
-
-    // For retrocompatibility purposes (pretty rare use case)
-    // See https://github.com/facebook/docusaurus/pull/1584
-    if (isValidElement(children)) {
-      return children;
-    }
-
-    return !children.includes('\n') ? (
-      <code {...props} />
-    ) : (
-      <CodeBlock {...props} />
+    const shouldBeInline = React.Children.toArray(props.children).every(
+      (el) => typeof el === 'string' && !el.includes('\n'),
     );
-  },
-  a: (props) => <Link {...props} />,
-  pre: (props) => {
-    const {children} = props;
 
-    // See comment for `code` above
-    if (isValidElement(children) && isValidElement(children?.props?.children)) {
-      return children.props.children;
-    }
-
-    return (
-      <CodeBlock
-        {...((isValidElement(children)
-          ? children?.props
-          : {...props}) as Props)}
-      />
-    );
+    return shouldBeInline ? <code {...props} /> : <CodeBlock {...props} />;
   },
+  a: (props) => <Link {...props} />,
+  pre: (props) => (
+    <CodeBlock
+      // If this pre is created by a ``` fenced codeblock, unwrap the children
+      {...(isValidElement(props.children) &&
+      props.children.props.originalType === 'code'
+        ? props.children?.props
+        : {...props})}
+    />
+  ),
   details: (props): JSX.Element => {
     const items = React.Children.toArray(props.children) as ReactElement[];
-    // Split summary item from the rest to pass it as a separate prop to the Detais theme component
+    // Split summary item from the rest to pass it as a separate prop to the Details theme component
     const summary: ReactElement<ComponentProps<'summary'>> = items.find(
       (item) => item?.props?.mdxType === 'summary',
     )!;
@@ -78,12 +67,12 @@ const MDXComponents: MDXComponentsObject = {
       </Details>
     );
   },
-  h1: Heading('h1'),
-  h2: Heading('h2'),
-  h3: Heading('h3'),
-  h4: Heading('h4'),
-  h5: Heading('h5'),
-  h6: Heading('h6'),
+  h1: (props) => <Heading as="h1" {...props} />,
+  h2: (props) => <Heading as="h2" {...props} />,
+  h3: (props) => <Heading as="h3" {...props} />,
+  h4: (props) => <Heading as="h4" {...props} />,
+  h5: (props) => <Heading as="h5" {...props} />,
+  h6: (props) => <Heading as="h6" {...props} />,
 };
 
 export default MDXComponents;

package/src/theme/MDXComponents/styles.css

@@ -9,3 +9,7 @@ ul.contains-task-list {
   padding-left: 0;
   list-style: none;
 }
+
+img {
+  height: auto;
+}

package/src/theme/MDXPage/index.tsx

@@ -19,18 +19,10 @@ import styles from './styles.module.css';
 function MDXPage(props: Props): JSX.Element {
   const {content: MDXPageContent} = props;
   const {
-    // TODO this frontmatter is not validated/normalized, it's the raw user-provided one. We should expose normalized one too!
-    frontMatter,
-    metadata,
+    metadata: {title, description, permalink, frontMatter},
   } = MDXPageContent;
-
-  const {
-    title,
-    description,
-    wrapperClassName,
-    hide_table_of_contents: hideTableOfContents,
-  } = frontMatter;
-  const {permalink} = metadata;
+  const {wrapperClassName, hide_table_of_contents: hideTableOfContents} =
+    frontMatter;
 
   return (
     <Layout

package/src/theme/Navbar/index.tsx

@@ -10,18 +10,18 @@ import clsx from 'clsx';
 import Translate from '@docusaurus/Translate';
 import SearchBar from '@theme/SearchBar';
 import Toggle from '@theme/Toggle';
-import useThemeContext from '@theme/hooks/useThemeContext';
 import {
   useThemeConfig,
   useMobileSecondaryMenuRenderer,
   usePrevious,
   useHistoryPopHandler,
+  useHideableNavbar,
+  useLockBodyScroll,
+  useWindowSize,
+  useColorMode,
 } from '@docusaurus/theme-common';
-import useHideableNavbar from '@theme/hooks/useHideableNavbar';
-import useLockBodyScroll from '@theme/hooks/useLockBodyScroll';
-import useWindowSize from '@theme/hooks/useWindowSize';
-import {useActivePlugin} from '@theme/hooks/useDocs';
-import NavbarItem, {Props as NavbarItemConfig} from '@theme/NavbarItem';
+import {useActivePlugin} from '@docusaurus/plugin-content-docs/client';
+import NavbarItem, {type Props as NavbarItemConfig} from '@theme/NavbarItem';
 import Logo from '@theme/Logo';
 import IconMenu from '@theme/IconMenu';
 import IconClose from '@theme/IconClose';
@@ -88,7 +88,7 @@ function useColorModeToggle() {
   const {
     colorMode: {disableSwitch},
   } = useThemeConfig();
-  const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
+  const {isDarkTheme, setLightTheme, setDarkTheme} = useColorMode();
   const toggle = useCallback(
     (e) => (e.target.checked ? setDarkTheme() : setLightTheme()),
     [setLightTheme, setDarkTheme],