@docusaurus/theme-classic 2.0.0-beta.0f144213d → 2.0.0-beta.11

package/src/theme/DocSidebar/index.tsx

@@ -5,240 +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,
+  MobileSecondaryMenuComponent,
+  ThemeClassNames,
+  useScrollPosition,
 } 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 useWindowSize from '@theme/hooks/useWindowSize';
 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/DocSidebarItem';
+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,
-      })}>
-      <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"
@@ -262,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
@@ -328,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} />}
@@ -363,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} />}
+    </>
+  );
+}

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

@@ -53,14 +53,6 @@
     padding: 0.5rem;
   }
 
-  .menuLinkText {
-    cursor: initial;
-  }
-
-  .menuLinkText:hover {
-    background: none;
-  }
-
   .menuWithAnnouncementBar {
     margin-bottom: var(--docusaurus-announcement-bar-height);
   }
@@ -112,13 +104,3 @@
   line-height: 0.9;
   width: 24px;
 }
-
-:global(.menu__list) :global(.menu__list) {
-  overflow-y: hidden;
-  will-change: height;
-  transition: height var(--ifm-transition-fast) linear;
-}
-
-:global(.menu__list-item--collapsed) :global(.menu__list) {
-  height: 0 !important;
-}

package/src/theme/DocSidebarItem/index.tsx

@@ -0,0 +1,242 @@
+/**
+ * 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, {useEffect, memo, useMemo} from 'react';
+import clsx from 'clsx';
+import {
+  isActiveSidebarItem,
+  usePrevious,
+  Collapsible,
+  useCollapsible,
+  findFirstCategoryLink,
+  ThemeClassNames,
+} 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 type {
+  PropSidebarItemCategory,
+  PropSidebarItemLink,
+} from '@docusaurus/plugin-content-docs';
+
+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
+}: Props): JSX.Element | null {
+  switch (item.type) {
+    case 'category':
+      if (item.items.length === 0) {
+        return null;
+      }
+      return <DocSidebarItemCategory item={item} {...props} />;
+    case 'link':
+    default:
+      return <DocSidebarItemLink item={item} {...props} />;
+  }
+}
+
+// If we navigate to a category and it becomes active, it should automatically expand itself
+function useAutoExpandActiveCategory({
+  isActive,
+  collapsed,
+  setCollapsed,
+}: {
+  isActive: boolean;
+  collapsed: boolean;
+  setCollapsed: (b: boolean) => void;
+}) {
+  const wasActive = usePrevious(isActive);
+  useEffect(() => {
+    const justBecameActive = isActive && !wasActive;
+    if (justBecameActive && collapsed) {
+      setCollapsed(false);
+    }
+  }, [isActive, wasActive, collapsed, setCollapsed]);
+}
+
+// When a collapsible category has no link, we still link it to its first child during SSR as a temporary fallback
+// This allows to be able to navigate inside the category even when JS fails to load, is delayed or simply disabled
+// React hydration becomes an optional progressive enhancement
+// see https://github.com/facebookincubator/infima/issues/36#issuecomment-772543188
+// see https://github.com/facebook/docusaurus/issues/3030
+function useCategoryHrefWithSSRFallback(
+  item: PropSidebarItemCategory,
+): string | undefined {
+  const isBrowser = useIsBrowser();
+  return useMemo(() => {
+    if (item.href) {
+      return item.href;
+    }
+    // In these cases, it's not necessary to render a fallback
+    // We skip the "findFirstCategoryLink" computation
+    if (isBrowser || !item.collapsible) {
+      return undefined;
+    }
+    return findFirstCategoryLink(item);
+  }, [item, isBrowser]);
+}
+
+function DocSidebarItemCategory({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  ...props
+}: Props & {item: PropSidebarItemCategory}) {
+  const {items, label, collapsible, className, href} = item;
+  const hrefWithSSRFallback = useCategoryHrefWithSSRFallback(item);
+
+  const isActive = isActiveSidebarItem(item, activePath);
+
+  const {collapsed, setCollapsed, toggleCollapsed} = useCollapsible({
+    // active categories are always initialized as expanded
+    // the default (item.collapsed) is only used for non-active categories
+    initialState: () => {
+      if (!collapsible) {
+        return false;
+      }
+      return isActive ? false : item.collapsed;
+    },
+  });
+
+  useAutoExpandActiveCategory({isActive, collapsed, setCollapsed});
+
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemCategory,
+        ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
+        'menu__list-item',
+        {
+          'menu__list-item--collapsed': collapsed,
+        },
+        className,
+      )}>
+      <div className="menu__list-item-collapsible">
+        <Link
+          className={clsx('menu__link', {
+            'menu__link--sublist': collapsible && !href,
+            'menu__link--active': isActive,
+            [styles.menuLinkText]: !collapsible,
+            [styles.hasHref]: !!hrefWithSSRFallback,
+          })}
+          onClick={
+            collapsible
+              ? (e) => {
+                  onItemClick?.(item);
+                  if (href) {
+                    setCollapsed(false);
+                  } else {
+                    e.preventDefault();
+                    toggleCollapsed();
+                  }
+                }
+              : () => {
+                  onItemClick?.(item);
+                }
+          }
+          href={collapsible ? hrefWithSSRFallback ?? '#' : hrefWithSSRFallback}
+          {...props}>
+          {label}
+        </Link>
+        {href && collapsible && (
+          <button
+            aria-label={translate(
+              {
+                id: 'theme.DocSidebarItem.toggleCollapsedCategoryAriaLabel',
+                message: "Toggle the collapsible sidebar category '{label}'",
+                description:
+                  'The ARIA label to toggle the collapsible sidebar category',
+              },
+              {label},
+            )}
+            type="button"
+            className="clean-btn menu__caret"
+            onClick={(e) => {
+              e.preventDefault();
+              toggleCollapsed();
+            }}
+          />
+        )}
+      </div>
+
+      <Collapsible lazy as="ul" className="menu__list" collapsed={collapsed}>
+        <DocSidebarItems
+          items={items}
+          tabIndex={collapsed ? -1 : 0}
+          onItemClick={onItemClick}
+          activePath={activePath}
+          level={level + 1}
+        />
+      </Collapsible>
+    </li>
+  );
+}
+
+function DocSidebarItemLink({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  ...props
+}: Props & {item: PropSidebarItemLink}) {
+  const {href, label, className} = item;
+  const isActive = isActiveSidebarItem(item, activePath);
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        'menu__list-item',
+        className,
+      )}
+      key={label}>
+      <Link
+        className={clsx('menu__link', {
+          'menu__link--active': isActive,
+        })}
+        aria-current={isActive ? 'page' : undefined}
+        to={href}
+        {...(isInternalUrl(href) && {
+          onClick: onItemClick ? () => onItemClick(item) : undefined,
+        })}
+        {...props}>
+        {isInternalUrl(href) ? (
+          label
+        ) : (
+          <span>
+            {label}
+            <IconExternalLink />
+          </span>
+        )}
+      </Link>
+    </li>
+  );
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 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) {
+  .menuLinkText {
+    cursor: initial;
+  }
+  .menuLinkText:hover {
+    background: none;
+  }
+
+  .menuLinkText.hasHref {
+    cursor: pointer;
+  }
+}