@docusaurus/theme-classic 2.0.0-beta.1decd6f80 → 2.0.0-beta.20

package/src/theme/DocSidebar/Desktop/Content/index.tsx

@@ -0,0 +1,55 @@
+/**
+ * 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, {useState} from 'react';
+import clsx from 'clsx';
+import {
+  ThemeClassNames,
+  useAnnouncementBar,
+  useScrollPosition,
+} from '@docusaurus/theme-common';
+import DocSidebarItems from '@theme/DocSidebarItems';
+import type {Props} from '@theme/DocSidebar/Desktop/Content';
+
+import styles from './styles.module.css';
+
+function useShowAnnouncementBar() {
+  const {isActive} = useAnnouncementBar();
+  const [showAnnouncementBar, setShowAnnouncementBar] = useState(isActive);
+
+  useScrollPosition(
+    ({scrollY}) => {
+      if (isActive) {
+        setShowAnnouncementBar(scrollY === 0);
+      }
+    },
+    [isActive],
+  );
+  return isActive && showAnnouncementBar;
+}
+
+export default function DocSidebarDesktopContent({
+  path,
+  sidebar,
+  className,
+}: Props): JSX.Element {
+  const showAnnouncementBar = useShowAnnouncementBar();
+
+  return (
+    <nav
+      className={clsx(
+        'menu thin-scrollbar',
+        styles.menu,
+        showAnnouncementBar && styles.menuWithAnnouncementBar,
+        className,
+      )}>
+      <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
+        <DocSidebarItems items={sidebar} activePath={path} level={1} />
+      </ul>
+    </nav>
+  );
+}

package/src/theme/DocSidebar/Desktop/Content/styles.module.css

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+
+@media (min-width: 997px) {
+  .menu {
+    flex-grow: 1;
+    padding: 0.5rem;
+  }
+  @supports (scrollbar-gutter: stable) {
+    .menu {
+      padding: 0.5rem 0 0.5rem 0.5rem;
+      scrollbar-gutter: stable;
+    }
+  }
+
+  .menuWithAnnouncementBar {
+    margin-bottom: var(--docusaurus-announcement-bar-height);
+  }
+}

package/src/theme/DocSidebar/Desktop/index.tsx

@@ -0,0 +1,40 @@
+/**
+ * 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 from 'react';
+import clsx from 'clsx';
+import {useThemeConfig} from '@docusaurus/theme-common';
+import Logo from '@theme/Logo';
+import CollapseButton from '@theme/DocSidebar/Desktop/CollapseButton';
+import Content from '@theme/DocSidebar/Desktop/Content';
+import type {Props} from '@theme/DocSidebar/Desktop';
+
+import styles from './styles.module.css';
+
+function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
+  const {
+    navbar: {hideOnScroll},
+    docs: {
+      sidebar: {hideable},
+    },
+  } = useThemeConfig();
+
+  return (
+    <div
+      className={clsx(
+        styles.sidebar,
+        hideOnScroll && styles.sidebarWithHideableNavbar,
+        isHidden && styles.sidebarHidden,
+      )}>
+      {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
+      <Content path={path} sidebar={sidebar} />
+      {hideable && <CollapseButton onClick={onCollapse} />}
+    </div>
+  );
+}
+
+export default React.memo(DocSidebarDesktop);

package/src/theme/DocSidebar/Desktop/styles.module.css

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+
+@media (min-width: 997px) {
+  .sidebar {
+    display: flex;
+    flex-direction: column;
+    max-height: 100vh;
+    height: 100%;
+    position: sticky;
+    top: 0;
+    padding-top: var(--ifm-navbar-height);
+    width: var(--doc-sidebar-width);
+    transition: opacity 50ms ease;
+  }
+
+  .sidebarWithHideableNavbar {
+    padding-top: 0;
+  }
+
+  .sidebarHidden {
+    opacity: 0;
+    height: 0;
+    overflow: hidden;
+    visibility: hidden;
+  }
+
+  .sidebarLogo {
+    display: flex !important;
+    align-items: center;
+    margin: 0 var(--ifm-navbar-padding-horizontal);
+    min-height: var(--ifm-navbar-height);
+    max-height: var(--ifm-navbar-height);
+    color: inherit !important;
+    text-decoration: none !important;
+  }
+
+  .sidebarLogo img {
+    margin-right: 0.5rem;
+    height: 2rem;
+  }
+}
+
+.sidebarLogo {
+  display: none;
+}

package/src/theme/DocSidebar/Mobile/index.tsx

@@ -0,0 +1,54 @@
+/**
+ * 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 from 'react';
+import clsx from 'clsx';
+import {
+  NavbarSecondaryMenuFiller,
+  type NavbarSecondaryMenuComponent,
+  ThemeClassNames,
+  useNavbarMobileSidebar,
+} from '@docusaurus/theme-common';
+import DocSidebarItems from '@theme/DocSidebarItems';
+import type {Props} from '@theme/DocSidebar/Mobile';
+
+// eslint-disable-next-line react/function-component-definition
+const DocSidebarMobileSecondaryMenu: NavbarSecondaryMenuComponent<Props> = ({
+  sidebar,
+  path,
+}) => {
+  const mobileSidebar = useNavbarMobileSidebar();
+  return (
+    <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) {
+            mobileSidebar.toggle();
+          }
+          if (item.type === 'link') {
+            mobileSidebar.toggle();
+          }
+        }}
+        level={1}
+      />
+    </ul>
+  );
+};
+
+function DocSidebarMobile(props: Props) {
+  return (
+    <NavbarSecondaryMenuFiller
+      component={DocSidebarMobileSecondaryMenu}
+      props={props}
+    />
+  );
+}
+
+export default React.memo(DocSidebarMobile);

package/src/theme/DocSidebar/index.tsx

@@ -5,355 +5,26 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useState, useCallback, useEffect, useRef, memo} from 'react';
-import clsx from 'clsx';
-import {useThemeConfig, isSamePath} from '@docusaurus/theme-common';
-import useUserPreferencesContext from '@theme/hooks/useUserPreferencesContext';
-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 React from 'react';
+import {useWindowSize} from '@docusaurus/theme-common';
 import type {Props} from '@theme/DocSidebar';
-import Logo from '@theme/Logo';
-import IconArrow from '@theme/IconArrow';
-import IconMenu from '@theme/IconMenu';
-import {translate} from '@docusaurus/Translate';
-
-import styles from './styles.module.css';
-
-const MOBILE_TOGGLE_SIZE = 24;
-
-function usePrevious(value) {
-  const ref = useRef(value);
-  useEffect(() => {
-    ref.current = value;
-  }, [value]);
-  return ref.current;
-}
-
-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();
-
-      if (!menuListHeight) {
-        handleMenuListHeight();
-      }
-
-      setTimeout(() => setCollapsed((state) => !state), 100);
-    },
-    [menuListHeight],
-  );
-
-  if (items.length === 0) {
-    return null;
-  }
-
-  return (
-    <li
-      className={clsx('menu__list-item', {
-        'menu__list-item--collapsed': collapsed,
-      })}>
-      <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>
-  );
-}
-
-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,
-          [styles.menuLinkExternal]: !isInternalUrl(href),
-        })}
-        to={href}
-        {...(isInternalUrl(href) && {
-          isNavLink: true,
-          exact: true,
-          onClick: onItemClick,
-        })}
-        {...props}>
-        {label}
-      </Link>
-    </li>
-  );
-}
-
-function useShowAnnouncementBar() {
-  const {isAnnouncementBarClosed} = useUserPreferencesContext();
-  const [showAnnouncementBar, setShowAnnouncementBar] = useState(
-    !isAnnouncementBarClosed,
-  );
-  useScrollPosition(({scrollY}) => {
-    if (!isAnnouncementBarClosed) {
-      setShowAnnouncementBar(scrollY === 0);
-    }
-  });
-  return showAnnouncementBar;
-}
-
-function useResponsiveSidebar() {
-  const [showResponsiveSidebar, setShowResponsiveSidebar] = useState(false);
-  useLockBodyScroll(showResponsiveSidebar);
+import DocSidebarDesktop from '@theme/DocSidebar/Desktop';
+import DocSidebarMobile from '@theme/DocSidebar/Mobile';
 
+export default function DocSidebar(props: Props): JSX.Element {
   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,
-  };
-}
+  // Desktop sidebar visible on hydration: need SSR rendering
+  const shouldRenderSidebarDesktop =
+    windowSize === 'desktop' || windowSize === 'ssr';
 
-function HideableSidebarButton({onClick}) {
-  return (
-    <button
-      type="button"
-      title={translate({
-        id: 'theme.docs.sidebar.collapseButtonTitle',
-        message: 'Collapse sidebar',
-        description: 'The title attribute for collapse button of doc sidebar',
-      })}
-      aria-label={translate({
-        id: 'theme.docs.sidebar.collapseButtonAriaLabel',
-        message: 'Collapse sidebar',
-        description: 'The title attribute for collapse button of doc sidebar',
-      })}
-      className={clsx(
-        'button button--secondary button--outline',
-        styles.collapseSidebarButton,
-      )}
-      onClick={onClick}>
-      <IconArrow className={styles.collapseSidebarButtonIcon} />
-    </button>
-  );
-}
+  // Mobile sidebar not visible on hydration: can avoid SSR rendering
+  const shouldRenderSidebarMobile = windowSize === 'mobile';
 
-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>
+    <>
+      {shouldRenderSidebarDesktop && <DocSidebarDesktop {...props} />}
+      {shouldRenderSidebarMobile && <DocSidebarMobile {...props} />}
+    </>
   );
 }
-
-function DocSidebar({
-  path,
-  sidebar,
-  sidebarCollapsible = true,
-  onCollapse,
-  isHidden,
-}: Props): JSX.Element | null {
-  const showAnnouncementBar = useShowAnnouncementBar();
-  const {
-    navbar: {hideOnScroll},
-    hideableSidebar,
-  } = useThemeConfig();
-  const {isAnnouncementBarClosed} = useUserPreferencesContext();
-
-  const {
-    showResponsiveSidebar,
-    closeResponsiveSidebar,
-    toggleResponsiveSidebar,
-  } = useResponsiveSidebar();
-
-  return (
-    <div
-      className={clsx(styles.sidebar, {
-        [styles.sidebarWithHideableNavbar]: hideOnScroll,
-        [styles.sidebarHidden]: isHidden,
-      })}>
-      {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
-      <div
-        className={clsx(
-          'menu',
-          'menu--responsive',
-          'thin-scrollbar',
-          styles.menu,
-          {
-            'menu--show': showResponsiveSidebar,
-            [styles.menuWithAnnouncementBar]:
-              !isAnnouncementBarClosed && showAnnouncementBar,
-          },
-        )}>
-        <ResponsiveSidebarButton
-          responsiveSidebarOpened={showResponsiveSidebar}
-          onClick={toggleResponsiveSidebar}
-        />
-        <ul className="menu__list">
-          <DocSidebarItems
-            items={sidebar}
-            onItemClick={closeResponsiveSidebar}
-            collapsible={sidebarCollapsible}
-            activePath={path}
-          />
-        </ul>
-      </div>
-      {hideableSidebar && <HideableSidebarButton onClick={onCollapse} />}
-    </div>
-  );
-}
-
-export default DocSidebar;