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

package/src/theme/{BlogPostAuthor/styles.module.css → DocPage/Layout/index.module.css}

@@ -5,8 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.image {
+.docPage {
+  display: flex;
   width: 100%;
-  height: 100%;
-  object-fit: cover;
+}
+
+.docsWrapper {
+  display: flex;
 }

package/src/theme/DocPage/Layout/index.tsx

@@ -0,0 +1,39 @@
+/**
+ * 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 Layout from '@theme/Layout';
+import BackToTopButton from '@theme/BackToTopButton';
+import type {Props} from '@theme/DocPage/Layout';
+import DocPageLayoutSidebar from '@theme/DocPage/Layout/Sidebar';
+import DocPageLayoutMain from '@theme/DocPage/Layout/Main';
+
+import styles from './index.module.css';
+
+import {useDocsSidebar} from '@docusaurus/theme-common';
+
+export default function DocPageLayout({children}: Props): JSX.Element {
+  const sidebar = useDocsSidebar();
+  const [hiddenSidebarContainer, setHiddenSidebarContainer] = useState(false);
+  return (
+    <Layout wrapperClassName={styles.docsWrapper}>
+      <BackToTopButton />
+      <div className={styles.docPage}>
+        {sidebar && (
+          <DocPageLayoutSidebar
+            sidebar={sidebar.items}
+            hiddenSidebarContainer={hiddenSidebarContainer}
+            setHiddenSidebarContainer={setHiddenSidebarContainer}
+          />
+        )}
+        <DocPageLayoutMain hiddenSidebarContainer={hiddenSidebarContainer}>
+          {children}
+        </DocPageLayoutMain>
+      </div>
+    </Layout>
+  );
+}

package/src/theme/DocPage/index.tsx

@@ -5,181 +5,52 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {type ReactNode, useState, useCallback} from 'react';
-import renderRoutes from '@docusaurus/renderRoutes';
-import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
-import Layout from '@theme/Layout';
-import DocSidebar from '@theme/DocSidebar';
+import React from 'react';
 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 DocPageLayout from '@theme/DocPage/Layout';
 
 import clsx from 'clsx';
-import styles from './styles.module.css';
 
 import {
   HtmlClassNameProvider,
   ThemeClassNames,
   docVersionSearchTag,
   DocsSidebarProvider,
-  useDocsSidebar,
   DocsVersionProvider,
+  useDocRouteMetadata,
 } from '@docusaurus/theme-common';
 import SearchMetadata from '@theme/SearchMetadata';
 
-type DocPageContentProps = {
-  readonly currentDocRoute: DocumentRoute;
-  readonly versionMetadata: PropVersionMetadata;
-  readonly children: ReactNode;
-  readonly sidebarName: string | undefined;
-};
-
-function DocPageContent({
-  currentDocRoute,
-  versionMetadata,
-  children,
-  sidebarName,
-}: DocPageContentProps): JSX.Element {
-  const sidebar = useDocsSidebar();
-  const {pluginId, version} = versionMetadata;
-  const [hiddenSidebarContainer, setHiddenSidebarContainer] = useState(false);
-  const [hiddenSidebar, setHiddenSidebar] = useState(false);
-  const toggleSidebar = useCallback(() => {
-    if (hiddenSidebar) {
-      setHiddenSidebar(false);
-    }
-
-    setHiddenSidebarContainer((value) => !value);
-  }, [hiddenSidebar]);
-
+export default function DocPage(props: Props): JSX.Element {
+  const {versionMetadata} = props;
+  const currentDocRouteMetadata = useDocRouteMetadata(props);
+  if (!currentDocRouteMetadata) {
+    return <NotFound />;
+  }
+  const {docElement, sidebarName, sidebarItems} = currentDocRouteMetadata;
   return (
     <>
       <SearchMetadata
-        version={version}
-        tag={docVersionSearchTag(pluginId, version)}
+        version={versionMetadata.version}
+        tag={docVersionSearchTag(
+          versionMetadata.pluginId,
+          versionMetadata.version,
+        )}
       />
-      <Layout>
-        <div className={styles.docPage}>
-          <BackToTopButton />
-
-          {sidebar && (
-            <aside
-              className={clsx(
-                ThemeClassNames.docs.docSidebarContainer,
-                styles.docSidebarContainer,
-                hiddenSidebarContainer && styles.docSidebarContainerHidden,
-              )}
-              onTransitionEnd={(e) => {
-                if (
-                  !e.currentTarget.classList.contains(
-                    styles.docSidebarContainer!,
-                  )
-                ) {
-                  return;
-                }
-
-                if (hiddenSidebarContainer) {
-                  setHiddenSidebar(true);
-                }
-              }}>
-              <DocSidebar
-                key={
-                  // Reset sidebar state on sidebar changes
-                  // See https://github.com/facebook/docusaurus/issues/3414
-                  sidebarName
-                }
-                sidebar={sidebar}
-                path={currentDocRoute.path}
-                onCollapse={toggleSidebar}
-                isHidden={hiddenSidebar}
-              />
-
-              {hiddenSidebar && (
-                <div
-                  className={styles.collapsedDocSidebar}
-                  title={translate({
-                    id: 'theme.docs.sidebar.expandButtonTitle',
-                    message: 'Expand sidebar',
-                    description:
-                      'The ARIA label and title attribute for expand button of doc sidebar',
-                  })}
-                  aria-label={translate({
-                    id: 'theme.docs.sidebar.expandButtonAriaLabel',
-                    message: 'Expand sidebar',
-                    description:
-                      'The ARIA label and title attribute for expand button of doc sidebar',
-                  })}
-                  tabIndex={0}
-                  role="button"
-                  onKeyDown={toggleSidebar}
-                  onClick={toggleSidebar}>
-                  <IconArrow className={styles.expandSidebarButtonIcon} />
-                </div>
-              )}
-            </aside>
-          )}
-          <main
-            className={clsx(
-              styles.docMainContainer,
-              (hiddenSidebarContainer || !sidebar) &&
-                styles.docMainContainerEnhanced,
-            )}>
-            <div
-              className={clsx(
-                'container padding-top--md padding-bottom--lg',
-                styles.docItemWrapper,
-                hiddenSidebarContainer && styles.docItemWrapperEnhanced,
-              )}>
-              {children}
-            </div>
-          </main>
-        </div>
-      </Layout>
+      <HtmlClassNameProvider
+        className={clsx(
+          // TODO: it should be removed from here
+          ThemeClassNames.wrapper.docsPages,
+          ThemeClassNames.page.docsDocPage,
+          props.versionMetadata.className,
+        )}>
+        <DocsVersionProvider version={versionMetadata}>
+          <DocsSidebarProvider name={sidebarName} items={sidebarItems}>
+            <DocPageLayout>{docElement}</DocPageLayout>
+          </DocsSidebarProvider>
+        </DocsVersionProvider>
+      </HtmlClassNameProvider>
     </>
   );
 }
-
-export default function DocPage(props: Props): JSX.Element {
-  const {
-    route: {routes: docRoutes},
-    versionMetadata,
-    location,
-  } = props;
-  const currentDocRoute = docRoutes.find((docRoute) =>
-    matchPath(location.pathname, docRoute),
-  );
-  if (!currentDocRoute) {
-    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 (
-    <HtmlClassNameProvider
-      className={clsx(
-        ThemeClassNames.wrapper.docsPages,
-        ThemeClassNames.page.docsDocPage,
-        versionMetadata.className,
-      )}>
-      <DocsVersionProvider version={versionMetadata}>
-        <DocsSidebarProvider sidebar={sidebar ?? null}>
-          <DocPageContent
-            currentDocRoute={currentDocRoute}
-            versionMetadata={versionMetadata}
-            sidebarName={sidebarName}>
-            {renderRoutes(docRoutes, {versionMetadata})}
-          </DocPageContent>
-        </DocsSidebarProvider>
-      </DocsVersionProvider>
-    </HtmlClassNameProvider>
-  );
-}

package/src/theme/DocPaginator/index.tsx

@@ -21,34 +21,31 @@ export default function DocPaginator(props: Props): JSX.Element {
         message: 'Docs pages navigation',
         description: 'The ARIA label for the docs pagination',
       })}>
-      <div className="pagination-nav__item">
-        {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__item pagination-nav__item--next">
-        {next && (
-          <PaginatorNavLink
-            {...next}
-            subLabel={
-              <Translate
-                id="theme.docs.paginator.next"
-                description="The label used to navigate to the next doc">
-                Next
-              </Translate>
-            }
-          />
-        )}
-      </div>
+      {previous && (
+        <PaginatorNavLink
+          {...previous}
+          subLabel={
+            <Translate
+              id="theme.docs.paginator.previous"
+              description="The label used to navigate to the previous doc">
+              Previous
+            </Translate>
+          }
+        />
+      )}
+      {next && (
+        <PaginatorNavLink
+          {...next}
+          subLabel={
+            <Translate
+              id="theme.docs.paginator.next"
+              description="The label used to navigate to the next doc">
+              Next
+            </Translate>
+          }
+          isNext
+        />
+      )}
     </nav>
   );
 }

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

@@ -6,13 +6,19 @@
  */
 
 :root {
-  --collapse-button-bg-color-dark: #2e333a;
+  --docusaurus-collapse-button-bg: transparent;
+  --docusaurus-collapse-button-bg-hover: rgb(0 0 0 / 10%);
+}
+
+[data-theme='dark']:root {
+  --docusaurus-collapse-button-bg: rgb(255 255 255 / 5%);
+  --docusaurus-collapse-button-bg-hover: rgb(255 255 255 / 10%);
 }
 
 @media (min-width: 997px) {
   .collapseSidebarButton {
     display: block !important;
-    background-color: var(--ifm-button-background-color);
+    background-color: var(--docusaurus-collapse-button-bg);
     height: 40px;
     position: sticky;
     bottom: 0;
@@ -29,13 +35,9 @@
     transform: rotate(0);
   }
 
-  [data-theme='dark'] .collapseSidebarButton {
-    background-color: var(--collapse-button-bg-color-dark);
-  }
-
-  [data-theme='dark'] .collapseSidebarButton:hover,
-  [data-theme='dark'] .collapseSidebarButton:focus {
-    background-color: var(--ifm-color-emphasis-200);
+  .collapseSidebarButton:hover,
+  .collapseSidebarButton:focus {
+    background-color: var(--docusaurus-collapse-button-bg-hover);
   }
 }
 

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

@@ -10,6 +10,12 @@
     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

@@ -18,7 +18,9 @@ import styles from './styles.module.css';
 function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
   const {
     navbar: {hideOnScroll},
-    hideableSidebar,
+    docs: {
+      sidebar: {hideable},
+    },
   } = useThemeConfig();
 
   return (
@@ -30,7 +32,7 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
       )}>
       {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
       <Content path={path} sidebar={sidebar} />
-      {hideableSidebar && <CollapseButton onClick={onCollapse} />}
+      {hideable && <CollapseButton onClick={onCollapse} />}
     </div>
   );
 }

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/{lib-next/theme/DocSidebarItem/styles.module.css → src/theme/DocSidebarItem/Html.module.css}

@@ -11,7 +11,3 @@
       var(--ifm-menu-link-padding-horizontal);
   }
 }
-
-.menuExternalLink {
-  align-items: center;
-}

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;
+}