@docusaurus/theme-classic 2.0.0-beta.15a2b59f9 → 2.0.0-beta.17

package/src/theme/DocPage/index.tsx

@@ -5,12 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {ReactNode, useState, useCallback} from 'react';
+import React, {type ReactNode, useState, useCallback} from 'react';
 import {MDXProvider} from '@mdx-js/react';
 
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import renderRoutes from '@docusaurus/renderRoutes';
-import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types';
+import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
 import Layout from '@theme/Layout';
 import DocSidebar from '@theme/DocSidebar';
 import MDXComponents from '@theme/MDXComponents';
@@ -18,50 +17,36 @@ import NotFound from '@theme/NotFound';
 import type {DocumentRoute} from '@theme/DocItem';
 import type {Props} from '@theme/DocPage';
 import IconArrow from '@theme/IconArrow';
+import BackToTopButton from '@theme/BackToTopButton';
 import {matchPath} from '@docusaurus/router';
 import {translate} from '@docusaurus/Translate';
 
 import clsx from 'clsx';
 import styles from './styles.module.css';
-import {ThemeClassNames, docVersionSearchTag} from '@docusaurus/theme-common';
+import {
+  ThemeClassNames,
+  docVersionSearchTag,
+  DocsSidebarProvider,
+  useDocsSidebar,
+  DocsVersionProvider,
+} from '@docusaurus/theme-common';
+import Head from '@docusaurus/Head';
 
 type DocPageContentProps = {
   readonly currentDocRoute: DocumentRoute;
   readonly versionMetadata: PropVersionMetadata;
   readonly children: ReactNode;
+  readonly sidebarName: string | undefined;
 };
 
-function getSidebar({versionMetadata, currentDocRoute}) {
-  function addTrailingSlash(str: string): string {
-    return str.endsWith('/') ? str : `${str}/`;
-  }
-  function removeTrailingSlash(str: string): string {
-    return str.endsWith('/') ? str.slice(0, -1) : str;
-  }
-
-  const {permalinkToSidebar, docsSidebars} = versionMetadata;
-
-  // With/without trailingSlash, we should always be able to get the appropriate sidebar
-  // note: docs plugin permalinks currently never have trailing slashes
-  // trailingSlash is handled globally at the framework level, not plugin level
-  const sidebarName =
-    permalinkToSidebar[currentDocRoute.path] ||
-    permalinkToSidebar[addTrailingSlash(currentDocRoute.path)] ||
-    permalinkToSidebar[removeTrailingSlash(currentDocRoute.path)];
-
-  const sidebar = docsSidebars[sidebarName];
-  return {sidebar, sidebarName};
-}
-
 function DocPageContent({
   currentDocRoute,
   versionMetadata,
   children,
+  sidebarName,
 }: DocPageContentProps): JSX.Element {
-  const {siteConfig, isClient} = useDocusaurusContext();
+  const sidebar = useDocsSidebar();
   const {pluginId, version} = versionMetadata;
-  const {sidebarName, sidebar} = getSidebar({versionMetadata, currentDocRoute});
-
   const [hiddenSidebarContainer, setHiddenSidebarContainer] = useState(false);
   const [hiddenSidebar, setHiddenSidebar] = useState(false);
   const toggleSidebar = useCallback(() => {
@@ -69,24 +54,29 @@ function DocPageContent({
       setHiddenSidebar(false);
     }
 
-    setHiddenSidebarContainer(!hiddenSidebarContainer);
+    setHiddenSidebarContainer((value) => !value);
   }, [hiddenSidebar]);
 
   return (
     <Layout
-      key={isClient}
-      wrapperClassName={ThemeClassNames.wrapper.docPages}
-      pageClassName={ThemeClassNames.page.docPage}
-      searchMetadatas={{
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
+      pageClassName={ThemeClassNames.page.docsDocPage}
+      searchMetadata={{
         version,
         tag: docVersionSearchTag(pluginId, version),
       }}>
       <div className={styles.docPage}>
+        <BackToTopButton />
+
         {sidebar && (
           <aside
-            className={clsx(styles.docSidebarContainer, {
-              [styles.docSidebarContainerHidden]: hiddenSidebarContainer,
-            })}
+            className={clsx(
+              ThemeClassNames.docs.docSidebarContainer,
+              styles.docSidebarContainer,
+              {
+                [styles.docSidebarContainerHidden]: hiddenSidebarContainer,
+              },
+            )}
             onTransitionEnd={(e) => {
               if (
                 !e.currentTarget.classList.contains(styles.docSidebarContainer)
@@ -106,9 +96,6 @@ function DocPageContent({
               }
               sidebar={sidebar}
               path={currentDocRoute.path}
-              sidebarCollapsible={
-                siteConfig.themeConfig?.sidebarCollapsible ?? true
-              }
               onCollapse={toggleSidebar}
               isHidden={hiddenSidebar}
             />
@@ -158,7 +145,7 @@ function DocPageContent({
   );
 }
 
-function DocPage(props: Props): JSX.Element {
+export default function DocPage(props: Props): JSX.Element {
   const {
     route: {routes: docRoutes},
     versionMetadata,
@@ -168,15 +155,32 @@ function DocPage(props: Props): JSX.Element {
     matchPath(location.pathname, docRoute),
   );
   if (!currentDocRoute) {
-    return <NotFound {...props} />;
+    return <NotFound />;
   }
+
+  // For now, the sidebarName is added as route config: not ideal!
+  const sidebarName = currentDocRoute.sidebar;
+
+  const sidebar = sidebarName
+    ? versionMetadata.docsSidebars[sidebarName]
+    : null;
+
   return (
-    <DocPageContent
-      currentDocRoute={currentDocRoute}
-      versionMetadata={versionMetadata}>
-      {renderRoutes(docRoutes, {versionMetadata})}
-    </DocPageContent>
+    <>
+      <Head>
+        {/* TODO we should add a core addRoute({htmlClassName}) action */}
+        <html className={versionMetadata.className} />
+      </Head>
+      <DocsVersionProvider version={versionMetadata}>
+        <DocsSidebarProvider sidebar={sidebar}>
+          <DocPageContent
+            currentDocRoute={currentDocRoute}
+            versionMetadata={versionMetadata}
+            sidebarName={sidebarName}>
+            {renderRoutes(docRoutes, {versionMetadata})}
+          </DocPageContent>
+        </DocsSidebarProvider>
+      </DocsVersionProvider>
+    </>
   );
 }
-
-export default DocPage;

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

@@ -20,6 +20,10 @@
   width: 100%;
 }
 
+.docSidebarContainer {
+  display: none;
+}
+
 @media (min-width: 997px) {
   .docMainContainer {
     flex-grow: 1;
@@ -31,6 +35,7 @@
   }
 
   .docSidebarContainer {
+    display: block;
     width: var(--doc-sidebar-width);
     margin-top: calc(-1 * var(--ifm-navbar-height));
     border-right: 1px solid var(--ifm-toc-border-color);
@@ -63,12 +68,13 @@
   .expandSidebarButtonIcon {
     transform: rotate(0);
   }
-  html[dir='rtl'] .expandSidebarButtonIcon {
+
+  [dir='rtl'] .expandSidebarButtonIcon {
     transform: rotate(180deg);
   }
 
-  html[data-theme='dark'] .collapsedDocSidebar:hover,
-  html[data-theme='dark'] .collapsedDocSidebar:focus {
+  [data-theme='dark'] .collapsedDocSidebar:hover,
+  [data-theme='dark'] .collapsedDocSidebar:focus {
     background-color: var(--collapse-button-bg-color-dark);
   }
 

package/src/theme/DocPaginator/index.tsx

@@ -6,12 +6,12 @@
  */
 
 import React from 'react';
-import Link from '@docusaurus/Link';
 import Translate, {translate} from '@docusaurus/Translate';
+import PaginatorNavLink from '@theme/PaginatorNavLink';
 import type {Props} from '@theme/DocPaginator';
 
-function DocPaginator(props: Props): JSX.Element {
-  const {metadata} = props;
+export default function DocPaginator(props: Props): JSX.Element {
+  const {previous, next} = props;
 
   return (
     <nav
@@ -22,41 +22,33 @@ function DocPaginator(props: Props): JSX.Element {
         description: 'The ARIA label for the docs pagination',
       })}>
       <div className="pagination-nav__item">
-        {metadata.previous && (
-          <Link
-            className="pagination-nav__link"
-            to={metadata.previous.permalink}>
-            <div className="pagination-nav__sublabel">
+        {previous && (
+          <PaginatorNavLink
+            {...previous}
+            subLabel={
               <Translate
                 id="theme.docs.paginator.previous"
                 description="The label used to navigate to the previous doc">
                 Previous
               </Translate>
-            </div>
-            <div className="pagination-nav__label">
-              &laquo; {metadata.previous.title}
-            </div>
-          </Link>
+            }
+          />
         )}
       </div>
       <div className="pagination-nav__item pagination-nav__item--next">
-        {metadata.next && (
-          <Link className="pagination-nav__link" to={metadata.next.permalink}>
-            <div className="pagination-nav__sublabel">
+        {next && (
+          <PaginatorNavLink
+            {...next}
+            subLabel={
               <Translate
                 id="theme.docs.paginator.next"
                 description="The label used to navigate to the next doc">
                 Next
               </Translate>
-            </div>
-            <div className="pagination-nav__label">
-              {metadata.next.title} &raquo;
-            </div>
-          </Link>
+            }
+          />
         )}
       </div>
     </nav>
   );
 }
-
-export default DocPaginator;

package/src/theme/DocSidebar/index.tsx

@@ -5,241 +5,41 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useState, useCallback, useEffect, useRef, memo} from 'react';
+import React, {useState} from 'react';
 import clsx from 'clsx';
 import {
   useThemeConfig,
-  isSamePath,
-  usePrevious,
   useAnnouncementBar,
+  MobileSecondaryMenuFiller,
+  type MobileSecondaryMenuComponent,
+  ThemeClassNames,
+  useScrollPosition,
+  useWindowSize,
 } from '@docusaurus/theme-common';
-import useLockBodyScroll from '@theme/hooks/useLockBodyScroll';
-import useWindowSize, {windowSizes} from '@theme/hooks/useWindowSize';
-import useScrollPosition from '@theme/hooks/useScrollPosition';
-import Link from '@docusaurus/Link';
-import isInternalUrl from '@docusaurus/isInternalUrl';
-import type {Props} from '@theme/DocSidebar';
 import Logo from '@theme/Logo';
 import IconArrow from '@theme/IconArrow';
-import IconMenu from '@theme/IconMenu';
-import IconExternalLink from '@theme/IconExternalLink';
 import {translate} from '@docusaurus/Translate';
+import DocSidebarItems from '@theme/DocSidebarItems';
+import type {Props} from '@theme/DocSidebar';
 
 import styles from './styles.module.css';
 
-const MOBILE_TOGGLE_SIZE = 24;
-
-const isActiveSidebarItem = (item, activePath) => {
-  if (item.type === 'link') {
-    return isSamePath(item.href, activePath);
-  }
-  if (item.type === 'category') {
-    return item.items.some((subItem) =>
-      isActiveSidebarItem(subItem, activePath),
-    );
-  }
-  return false;
-};
-
-// Optimize sidebar at each "level"
-// TODO this item should probably not receive the "activePath" props
-// TODO this triggers whole sidebar re-renders on navigation
-const DocSidebarItems = memo(function DocSidebarItems({
-  items,
-  ...props
-}: any): JSX.Element {
-  return items.map((item, index) => (
-    <DocSidebarItem
-      key={index} // sidebar is static, the index does not change
-      item={item}
-      {...props}
-    />
-  ));
-});
-
-function DocSidebarItem(props): JSX.Element {
-  switch (props.item.type) {
-    case 'category':
-      return <DocSidebarItemCategory {...props} />;
-    case 'link':
-    default:
-      return <DocSidebarItemLink {...props} />;
-  }
-}
-
-function DocSidebarItemCategory({
-  item,
-  onItemClick,
-  collapsible,
-  activePath,
-  ...props
-}) {
-  const {items, label} = item;
-
-  const isActive = isActiveSidebarItem(item, activePath);
-  const wasActive = usePrevious(isActive);
-
-  // active categories are always initialized as expanded
-  // the default (item.collapsed) is only used for non-active categories
-  const [collapsed, setCollapsed] = useState(() => {
-    if (!collapsible) {
-      return false;
-    }
-    return isActive ? false : item.collapsed;
-  });
-
-  const menuListRef = useRef<HTMLUListElement>(null);
-  const [menuListHeight, setMenuListHeight] = useState<string | undefined>(
-    undefined,
-  );
-  const handleMenuListHeight = (calc = true) => {
-    setMenuListHeight(
-      calc ? `${menuListRef.current?.scrollHeight}px` : undefined,
-    );
-  };
-
-  // If we navigate to a category, it should automatically expand itself
-  useEffect(() => {
-    const justBecameActive = isActive && !wasActive;
-    if (justBecameActive && collapsed) {
-      setCollapsed(false);
-    }
-  }, [isActive, wasActive, collapsed]);
-
-  const handleItemClick = useCallback(
-    (e) => {
-      e.preventDefault();
+function useShowAnnouncementBar() {
+  const {isActive} = useAnnouncementBar();
+  const [showAnnouncementBar, setShowAnnouncementBar] = useState(isActive);
 
-      if (!menuListHeight) {
-        handleMenuListHeight();
+  useScrollPosition(
+    ({scrollY}) => {
+      if (isActive) {
+        setShowAnnouncementBar(scrollY === 0);
       }
-
-      setTimeout(() => setCollapsed((state) => !state), 100);
     },
-    [menuListHeight],
-  );
-
-  if (items.length === 0) {
-    return null;
-  }
-
-  return (
-    <li
-      className={clsx('menu__list-item', {
-        'menu__list-item--collapsed': collapsed,
-      })}>
-      {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
-      <a
-        className={clsx('menu__link', {
-          'menu__link--sublist': collapsible,
-          'menu__link--active': collapsible && isActive,
-          [styles.menuLinkText]: !collapsible,
-        })}
-        onClick={collapsible ? handleItemClick : undefined}
-        href={collapsible ? '#' : undefined}
-        {...props}>
-        {label}
-      </a>
-      <ul
-        className="menu__list"
-        ref={menuListRef}
-        style={{
-          height: menuListHeight,
-        }}
-        onTransitionEnd={() => {
-          if (!collapsed) {
-            handleMenuListHeight(false);
-          }
-        }}>
-        <DocSidebarItems
-          items={items}
-          tabIndex={collapsed ? '-1' : '0'}
-          onItemClick={onItemClick}
-          collapsible={collapsible}
-          activePath={activePath}
-        />
-      </ul>
-    </li>
+    [isActive],
   );
+  return isActive && showAnnouncementBar;
 }
 
-function DocSidebarItemLink({
-  item,
-  onItemClick,
-  activePath,
-  collapsible: _collapsible,
-  ...props
-}) {
-  const {href, label} = item;
-  const isActive = isActiveSidebarItem(item, activePath);
-  return (
-    <li className="menu__list-item" key={label}>
-      <Link
-        className={clsx('menu__link', {
-          'menu__link--active': isActive,
-        })}
-        to={href}
-        {...(isInternalUrl(href) && {
-          isNavLink: true,
-          exact: true,
-          onClick: onItemClick,
-        })}
-        {...props}>
-        {isInternalUrl(href) ? (
-          label
-        ) : (
-          <span>
-            {label}
-            <IconExternalLink />
-          </span>
-        )}
-      </Link>
-    </li>
-  );
-}
-
-function useShowAnnouncementBar() {
-  const {isClosed} = useAnnouncementBar();
-  const [showAnnouncementBar, setShowAnnouncementBar] = useState(!isClosed);
-  useScrollPosition(({scrollY}) => {
-    if (!isClosed) {
-      setShowAnnouncementBar(scrollY === 0);
-    }
-  });
-  return showAnnouncementBar;
-}
-
-function useResponsiveSidebar() {
-  const [showResponsiveSidebar, setShowResponsiveSidebar] = useState(false);
-  useLockBodyScroll(showResponsiveSidebar);
-
-  const windowSize = useWindowSize();
-  useEffect(() => {
-    if (windowSize === windowSizes.desktop) {
-      setShowResponsiveSidebar(false);
-    }
-  }, [windowSize]);
-
-  const closeResponsiveSidebar = useCallback(
-    (e) => {
-      e.target.blur();
-      setShowResponsiveSidebar(false);
-    },
-    [setShowResponsiveSidebar],
-  );
-
-  const toggleResponsiveSidebar = useCallback(() => {
-    setShowResponsiveSidebar((value) => !value);
-  }, [setShowResponsiveSidebar]);
-
-  return {
-    showResponsiveSidebar,
-    closeResponsiveSidebar,
-    toggleResponsiveSidebar,
-  };
-}
-
-function HideableSidebarButton({onClick}) {
+function HideableSidebarButton({onClick}: {onClick: React.MouseEventHandler}) {
   return (
     <button
       type="button"
@@ -263,63 +63,12 @@ function HideableSidebarButton({onClick}) {
   );
 }
 
-function ResponsiveSidebarButton({responsiveSidebarOpened, onClick}) {
-  return (
-    <button
-      aria-label={
-        responsiveSidebarOpened
-          ? translate({
-              id: 'theme.docs.sidebar.responsiveCloseButtonLabel',
-              message: 'Close menu',
-              description:
-                'The ARIA label for close button of mobile doc sidebar',
-            })
-          : translate({
-              id: 'theme.docs.sidebar.responsiveOpenButtonLabel',
-              message: 'Open menu',
-              description:
-                'The ARIA label for open button of mobile doc sidebar',
-            })
-      }
-      aria-haspopup="true"
-      className="button button--secondary button--sm menu__button"
-      type="button"
-      onClick={onClick}>
-      {responsiveSidebarOpened ? (
-        <span
-          className={clsx(styles.sidebarMenuIcon, styles.sidebarMenuCloseIcon)}>
-          &times;
-        </span>
-      ) : (
-        <IconMenu
-          className={styles.sidebarMenuIcon}
-          height={MOBILE_TOGGLE_SIZE}
-          width={MOBILE_TOGGLE_SIZE}
-        />
-      )}
-    </button>
-  );
-}
-
-function DocSidebar({
-  path,
-  sidebar,
-  sidebarCollapsible = true,
-  onCollapse,
-  isHidden,
-}: Props): JSX.Element | null {
+function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
   const showAnnouncementBar = useShowAnnouncementBar();
   const {
     navbar: {hideOnScroll},
     hideableSidebar,
   } = useThemeConfig();
-  const {isClosed: isAnnouncementBarClosed} = useAnnouncementBar();
-
-  const {
-    showResponsiveSidebar,
-    closeResponsiveSidebar,
-    toggleResponsiveSidebar,
-  } = useResponsiveSidebar();
 
   return (
     <div
@@ -329,34 +78,11 @@ function DocSidebar({
       })}>
       {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
       <nav
-        className={clsx(
-          'menu',
-          'menu--responsive',
-          'thin-scrollbar',
-          styles.menu,
-          {
-            'menu--show': showResponsiveSidebar,
-            [styles.menuWithAnnouncementBar]:
-              !isAnnouncementBarClosed && showAnnouncementBar,
-          },
-        )}
-        aria-label={translate({
-          id: 'theme.docs.sidebar.navAriaLabel',
-          message: 'Sidebar navigation',
-          description: 'The ARIA label for documentation menu',
+        className={clsx('menu thin-scrollbar', styles.menu, {
+          [styles.menuWithAnnouncementBar]: showAnnouncementBar,
         })}>
-        <ResponsiveSidebarButton
-          responsiveSidebarOpened={showResponsiveSidebar}
-          onClick={toggleResponsiveSidebar}
-        />
-
-        <ul className="menu__list">
-          <DocSidebarItems
-            items={sidebar}
-            onItemClick={closeResponsiveSidebar}
-            collapsible={sidebarCollapsible}
-            activePath={path}
-          />
+        <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
+          <DocSidebarItems items={sidebar} activePath={path} level={1} />
         </ul>
       </nav>
       {hideableSidebar && <HideableSidebarButton onClick={onCollapse} />}
@@ -364,4 +90,56 @@ function DocSidebar({
   );
 }
 
-export default DocSidebar;
+// eslint-disable-next-line react/function-component-definition
+const DocSidebarMobileSecondaryMenu: MobileSecondaryMenuComponent<Props> = ({
+  toggleSidebar,
+  sidebar,
+  path,
+}) => (
+  <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
+    <DocSidebarItems
+      items={sidebar}
+      activePath={path}
+      onItemClick={(item) => {
+        // Mobile sidebar should only be closed if the category has a link
+        if (item.type === 'category' && item.href) {
+          toggleSidebar();
+        }
+        if (item.type === 'link') {
+          toggleSidebar();
+        }
+      }}
+      level={1}
+    />
+  </ul>
+);
+
+function DocSidebarMobile(props: Props) {
+  return (
+    <MobileSecondaryMenuFiller
+      component={DocSidebarMobileSecondaryMenu}
+      props={props}
+    />
+  );
+}
+
+const DocSidebarDesktopMemo = React.memo(DocSidebarDesktop);
+const DocSidebarMobileMemo = React.memo(DocSidebarMobile);
+
+export default function DocSidebar(props: Props): JSX.Element {
+  const windowSize = useWindowSize();
+
+  // Desktop sidebar visible on hydration: need SSR rendering
+  const shouldRenderSidebarDesktop =
+    windowSize === 'desktop' || windowSize === 'ssr';
+
+  // Mobile sidebar not visible on hydration: can avoid SSR rendering
+  const shouldRenderSidebarMobile = windowSize === 'mobile';
+
+  return (
+    <>
+      {shouldRenderSidebarDesktop && <DocSidebarDesktopMemo {...props} />}
+      {shouldRenderSidebarMobile && <DocSidebarMobileMemo {...props} />}
+    </>
+  );
+}