@docusaurus/theme-classic 2.0.0-beta.15d451942 → 2.0.0-beta.18

package/lib-next/theme/DocSidebar/Mobile/index.js

@@ -0,0 +1,49 @@
+/**
+ * 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,
+  ThemeClassNames,
+  useNavbarMobileSidebar,
+} from '@docusaurus/theme-common';
+import DocSidebarItems from '@theme/DocSidebarItems';
+
+// eslint-disable-next-line react/function-component-definition
+const DocSidebarMobileSecondaryMenu = ({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) {
+  return (
+    <NavbarSecondaryMenuFiller
+      component={DocSidebarMobileSecondaryMenu}
+      props={props}
+    />
+  );
+}
+
+export default React.memo(DocSidebarMobile);

package/lib-next/theme/DocSidebar/index.js

@@ -4,341 +4,21 @@
  * 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, 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 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;
+import React from 'react';
+import {useWindowSize} from '@docusaurus/theme-common';
+import DocSidebarDesktop from '@theme/DocSidebar/Desktop';
+import DocSidebarMobile from '@theme/DocSidebar/Mobile';
+export default function DocSidebar(props) {
+  const windowSize = useWindowSize(); // Desktop sidebar visible on hydration: need SSR rendering
 
-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}) {
-  return items.map((item, index) => (
-    <DocSidebarItem
-      key={index} // sidebar is static, the index does not change
-      item={item}
-      {...props}
-    />
-  ));
-});
-
-function DocSidebarItem(props) {
-  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(null);
-  const [menuListHeight, setMenuListHeight] = useState(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;
-  }
+  const shouldRenderSidebarDesktop =
+    windowSize === 'desktop' || windowSize === 'ssr'; // Mobile sidebar not visible on hydration: can avoid SSR rendering
 
+  const shouldRenderSidebarMobile = windowSize === 'mobile';
   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>
+    <>
+      {shouldRenderSidebarDesktop && <DocSidebarDesktop {...props} />}
+      {shouldRenderSidebarMobile && <DocSidebarMobile {...props} />}
+    </>
   );
 }
-
-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);
-  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}) {
-  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>
-  );
-}
-
-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,
-}) {
-  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;

package/lib-next/theme/DocSidebarItem/index.js

@@ -0,0 +1,265 @@
+/**
+ * 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, useMemo} from 'react';
+import clsx from 'clsx';
+import {
+  isActiveSidebarItem,
+  usePrevious,
+  Collapsible,
+  useCollapsible,
+  findFirstCategoryLink,
+  ThemeClassNames,
+  useThemeConfig,
+  useDocSidebarItemsExpandedState,
+  isSamePath,
+} 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 DocSidebarItems from '@theme/DocSidebarItems';
+import styles from './styles.module.css';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+export default function DocSidebarItem({item, ...props}) {
+  switch (item.type) {
+    case 'category':
+      return <DocSidebarItemCategory item={item} {...props} />;
+
+    case 'html':
+      return <DocSidebarItemHtml 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}) {
+  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) {
+  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,
+  index,
+  ...props
+}) {
+  const {items, label, collapsible, className, href} = item;
+  const hrefWithSSRFallback = useCategoryHrefWithSSRFallback(item);
+  const isActive = isActiveSidebarItem(item, activePath);
+  const isCurrentPage = isSamePath(href, activePath);
+  const {collapsed, setCollapsed} = 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,
+  });
+  const {expandedItem, setExpandedItem} = useDocSidebarItemsExpandedState();
+
+  function updateCollapsed(toCollapsed = !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
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemCategory,
+        ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
+        'menu__list-item',
+        {
+          'menu__list-item--collapsed': collapsed,
+        },
+        className,
+      )}>
+      <div
+        className={clsx('menu__list-item-collapsible', {
+          'menu__list-item-collapsible--active': isCurrentPage,
+        })}>
+        <Link
+          className={clsx('menu__link', {
+            'menu__link--sublist': collapsible,
+            'menu__link--sublist-caret': !href,
+            'menu__link--active': isActive,
+          })}
+          onClick={
+            collapsible
+              ? (e) => {
+                  onItemClick?.(item);
+
+                  if (href) {
+                    updateCollapsed(false);
+                  } else {
+                    e.preventDefault();
+                    updateCollapsed();
+                  }
+                }
+              : () => {
+                  onItemClick?.(item);
+                }
+          }
+          aria-current={isCurrentPage ? 'page' : undefined}
+          aria-expanded={collapsible ? !collapsed : undefined}
+          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();
+              updateCollapsed();
+            }}
+          />
+        )}
+      </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 DocSidebarItemHtml({item, level, index}) {
+  const {value, defaultStyle, className} = item;
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        defaultStyle && `${styles.menuHtmlItem} menu__list-item`,
+        className,
+      )}
+      key={index} // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{
+        __html: value,
+      }}
+    />
+  );
+}
+
+function DocSidebarItemLink({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}) {
+  const {href, label, className} = item;
+  const isActive = isActiveSidebarItem(item, activePath);
+  const isInternalLink = isInternalUrl(href);
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        'menu__list-item',
+        className,
+      )}
+      key={label}>
+      <Link
+        className={clsx(
+          'menu__link',
+          !isInternalLink && styles.menuExternalLink,
+          {
+            'menu__link--active': isActive,
+          },
+        )}
+        aria-current={isActive ? 'page' : undefined}
+        to={href}
+        {...(isInternalLink && {
+          onClick: onItemClick ? () => onItemClick(item) : undefined,
+        })}
+        {...props}>
+        {label}
+        {!isInternalLink && <IconExternalLink />}
+      </Link>
+    </li>
+  );
+}

package/lib-next/theme/DocSidebarItem/styles.module.css

@@ -0,0 +1,17 @@
+/**
+ * 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) {
+  .menuHtmlItem {
+    padding: var(--ifm-menu-link-padding-vertical)
+      var(--ifm-menu-link-padding-horizontal);
+  }
+}
+
+.menuExternalLink {
+  align-items: center;
+}