@docusaurus/theme-classic 2.0.0-beta.16 → 2.0.0-beta.19

package/src/theme/DocSidebar/index.tsx

@@ -5,126 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useState} from 'react';
-import clsx from 'clsx';
-import {
-  useThemeConfig,
-  useAnnouncementBar,
-  MobileSecondaryMenuFiller,
-  type MobileSecondaryMenuComponent,
-  ThemeClassNames,
-  useScrollPosition,
-  useWindowSize,
-} from '@docusaurus/theme-common';
-import Logo from '@theme/Logo';
-import IconArrow from '@theme/IconArrow';
-import {translate} from '@docusaurus/Translate';
-import DocSidebarItems from '@theme/DocSidebarItems';
+import React from 'react';
+import {useWindowSize} from '@docusaurus/theme-common';
 import type {Props} from '@theme/DocSidebar';
-
-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;
-}
-
-function HideableSidebarButton({onClick}: {onClick: React.MouseEventHandler}) {
-  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 DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
-  const showAnnouncementBar = useShowAnnouncementBar();
-  const {
-    navbar: {hideOnScroll},
-    hideableSidebar,
-  } = useThemeConfig();
-
-  return (
-    <div
-      className={clsx(styles.sidebar, {
-        [styles.sidebarWithHideableNavbar]: hideOnScroll,
-        [styles.sidebarHidden]: isHidden,
-      })}>
-      {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
-      <nav
-        className={clsx('menu thin-scrollbar', styles.menu, {
-          [styles.menuWithAnnouncementBar]: showAnnouncementBar,
-        })}>
-        <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
-          <DocSidebarItems items={sidebar} activePath={path} level={1} />
-        </ul>
-      </nav>
-      {hideableSidebar && <HideableSidebarButton onClick={onCollapse} />}
-    </div>
-  );
-}
-
-// 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);
+import DocSidebarDesktop from '@theme/DocSidebar/Desktop';
+import DocSidebarMobile from '@theme/DocSidebar/Mobile';
 
 export default function DocSidebar(props: Props): JSX.Element {
   const windowSize = useWindowSize();
@@ -138,8 +23,8 @@ export default function DocSidebar(props: Props): JSX.Element {
 
   return (
     <>
-      {shouldRenderSidebarDesktop && <DocSidebarDesktopMemo {...props} />}
-      {shouldRenderSidebarMobile && <DocSidebarMobileMemo {...props} />}
+      {shouldRenderSidebarDesktop && <DocSidebarDesktop {...props} />}
+      {shouldRenderSidebarMobile && <DocSidebarMobile {...props} />}
     </>
   );
 }

package/src/theme/DocSidebarItem/Category.tsx

@@ -0,0 +1,210 @@
+/**
+ * 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, {type ComponentProps, 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 {translate} from '@docusaurus/Translate';
+
+import DocSidebarItems from '@theme/DocSidebarItems';
+import type {Props} from '@theme/DocSidebarItem/Category';
+
+import useIsBrowser from '@docusaurus/useIsBrowser';
+
+// 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: Props['item'],
+): 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 CollapseButton({
+  categoryLabel,
+  onClick,
+}: {
+  categoryLabel: string;
+  onClick: ComponentProps<'button'>['onClick'];
+}) {
+  return (
+    <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: categoryLabel},
+      )}
+      type="button"
+      className="clean-btn menu__caret"
+      onClick={onClick}
+    />
+  );
+}
+
+export default function DocSidebarItemCategory({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}: Props): JSX.Element {
+  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: boolean = !collapsed) {
+    setExpandedItem(toCollapsed ? null : index);
+    setCollapsed(toCollapsed);
+  }
+  const {
+    docs: {
+      sidebar: {autoCollapseCategories},
+    },
+  } = useThemeConfig();
+  useEffect(() => {
+    if (
+      collapsible &&
+      expandedItem &&
+      expandedItem !== index &&
+      autoCollapseCategories
+    ) {
+      setCollapsed(true);
+    }
+  }, [collapsible, expandedItem, index, setCollapsed, autoCollapseCategories]);
+
+  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 && collapsible,
+            '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 && (
+          <CollapseButton
+            categoryLabel={label}
+            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>
+  );
+}

package/src/theme/DocSidebarItem/Html.tsx

@@ -0,0 +1,34 @@
+/**
+ * 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 {ThemeClassNames} from '@docusaurus/theme-common';
+import type {Props} from '@theme/DocSidebarItem/Html';
+
+import styles from './Html.module.css';
+
+export default function DocSidebarItemHtml({
+  item,
+  level,
+  index,
+}: Props): JSX.Element {
+  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}}
+    />
+  );
+}

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

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+
+.menuExternalLink {
+  align-items: center;
+}

package/src/theme/DocSidebarItem/Link.tsx

@@ -0,0 +1,58 @@
+/**
+ * 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 {isActiveSidebarItem, ThemeClassNames} from '@docusaurus/theme-common';
+import Link from '@docusaurus/Link';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import IconExternalLink from '@theme/IconExternalLink';
+
+import type {Props} from '@theme/DocSidebarItem/Link';
+
+import styles from './Link.module.css';
+
+export default function DocSidebarItemLink({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}: Props): JSX.Element {
+  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>
+  );
+}