@docusaurus/theme-classic 0.0.0-4224 → 0.0.0-4241

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "0.0.0-4224",
+  "version": "0.0.0-4241",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -14,30 +14,30 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "tsc --noEmit && yarn babel:lib && yarn babel:lib-next && yarn prettier:lib-next",
+    "build": "tsc --noEmit && yarn babel:lib && yarn babel:lib-next && yarn format:lib-next",
     "watch": "concurrently --names \"lib,lib-next,tsc\" --kill-others \"yarn babel:lib --watch\" \"yarn babel:lib-next --watch\" \"yarn tsc --watch\"",
     "babel:lib": "cross-env BABEL_ENV=lib babel src -d lib --extensions \".tsx,.ts\" --ignore \"**/*.d.ts\" --copy-files",
     "babel:lib-next": "cross-env BABEL_ENV=lib-next babel src -d lib-next --extensions \".tsx,.ts\" --ignore \"**/*.d.ts\" --copy-files",
-    "prettier": "prettier --config ../../.prettierrc --ignore-path ../../.prettierignore --write \"**/*.{js,ts,jsx,tsc}\"",
-    "prettier:lib-next": "prettier --config ../../.prettierrc --write \"lib-next/**/*.{js,ts,jsx,tsc}\"",
+    "format": "prettier --config ../../.prettierrc --ignore-path ../../.prettierignore --write \"**/*.{js,ts,jsx,tsc}\"",
+    "format:lib-next": "prettier --config ../../.prettierrc --write \"lib-next/**/*.{js,ts,jsx,tsc}\"",
     "update-code-translations": "node -e 'require(\"./update-code-translations.js\").run()'"
   },
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4224",
-    "@docusaurus/plugin-content-blog": "0.0.0-4224",
-    "@docusaurus/plugin-content-docs": "0.0.0-4224",
-    "@docusaurus/plugin-content-pages": "0.0.0-4224",
-    "@docusaurus/theme-common": "0.0.0-4224",
-    "@docusaurus/theme-translations": "0.0.0-4224",
-    "@docusaurus/utils": "0.0.0-4224",
-    "@docusaurus/utils-validation": "0.0.0-4224",
+    "@docusaurus/core": "0.0.0-4241",
+    "@docusaurus/plugin-content-blog": "0.0.0-4241",
+    "@docusaurus/plugin-content-docs": "0.0.0-4241",
+    "@docusaurus/plugin-content-pages": "0.0.0-4241",
+    "@docusaurus/theme-common": "0.0.0-4241",
+    "@docusaurus/theme-translations": "0.0.0-4241",
+    "@docusaurus/utils": "0.0.0-4241",
+    "@docusaurus/utils-validation": "0.0.0-4241",
     "@mdx-js/mdx": "^1.6.21",
     "@mdx-js/react": "^1.6.21",
     "chalk": "^4.1.2",
     "clsx": "^1.1.1",
     "copy-text-to-clipboard": "^3.0.1",
     "globby": "^11.0.2",
-    "infima": "0.2.0-alpha.34",
+    "infima": "0.2.0-alpha.36",
     "lodash": "^4.17.20",
     "postcss": "^8.3.7",
     "prism-react-renderer": "^1.2.1",
@@ -46,8 +46,8 @@
     "rtlcss": "^3.3.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4224",
-    "@docusaurus/types": "0.0.0-4224",
+    "@docusaurus/module-type-aliases": "0.0.0-4241",
+    "@docusaurus/types": "0.0.0-4241",
     "@types/mdx-js__react": "^1.5.4",
     "@types/parse-numeric-range": "^0.0.1",
     "@types/rtlcss": "^3.1.1",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "ccb6ce579166aa0854f411605787e39c90d9eaa0"
+  "gitHead": "c9609b8c3e97c86812a67a377c7f0ebdca8b07f0"
 }

package/src/theme/DocCard/index.tsx

@@ -0,0 +1,100 @@
+/**
+ * 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, {ReactNode} from 'react';
+import Link from '@docusaurus/Link';
+import {
+  PropSidebarItemCategory,
+  PropSidebarItemLink,
+} from '@docusaurus/plugin-content-docs';
+import type {Props} from '@theme/DocCard';
+import {findFirstCategoryLink, useDocById} from '@docusaurus/theme-common';
+import clsx from 'clsx';
+import styles from './styles.module.css';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+
+function CardContainer({
+  href,
+  children,
+}: {
+  href?: string;
+  children: ReactNode;
+}): JSX.Element {
+  const className = clsx(
+    'card margin-bottom--lg padding--lg',
+    styles.cardContainer,
+    href && styles.cardContainerLink,
+  );
+  return href ? (
+    <Link href={href} className={className}>
+      {children}
+    </Link>
+  ) : (
+    <div className={className}>{children}</div>
+  );
+}
+
+function CardLayout({
+  href,
+  icon,
+  title,
+  description,
+}: {
+  href?: string;
+  icon: ReactNode;
+  title: string;
+  description?: string;
+}): JSX.Element {
+  return (
+    <CardContainer href={href}>
+      <h2 className={clsx('text--truncate', styles.cardTitle)} title={title}>
+        {icon} {title}
+      </h2>
+      <div
+        className={clsx('text--truncate', styles.cardDescription)}
+        title={description}>
+        {description}
+      </div>
+    </CardContainer>
+  );
+}
+
+function CardCategory({item}: {item: PropSidebarItemCategory}): JSX.Element {
+  const href = findFirstCategoryLink(item);
+  return (
+    <CardLayout
+      href={href}
+      icon="🗃️"
+      title={item.label}
+      description={`${item.items.length} items`}
+    />
+  );
+}
+
+function CardLink({item}: {item: PropSidebarItemLink}): JSX.Element {
+  const icon = isInternalUrl(item.href) ? '📄️' : '🔗';
+  const doc = useDocById(item.docId ?? undefined);
+  return (
+    <CardLayout
+      href={item.href}
+      icon={icon}
+      title={item.label}
+      description={doc?.description}
+    />
+  );
+}
+
+export default function DocCard({item}: Props): JSX.Element {
+  switch (item.type) {
+    case 'link':
+      return <CardLink item={item} />;
+    case 'category':
+      return <CardCategory item={item} />;
+    default:
+      throw new Error(`unknown item type ${JSON.stringify(item)}`);
+  }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+
+.cardContainer {
+  height: 8rem;
+
+  color: var(--ifm-color-emphasis-800);
+  --ifm-link-color: var(--ifm-color-emphasis-800);
+  --ifm-link-hover-color: var(--ifm-color-emphasis-800);
+  --ifm-link-hover-decoration: none;
+
+  /* box-shadow: var(--ifm-global-shadow-lw); */
+  box-shadow: 0 1.5px 3px 0 rgba(0, 0, 0, 0.15);
+  border: 1px solid var(--ifm-color-emphasis-200);
+  transition: box-shadow var(--ifm-transition-fast) ease,
+    background-color var(--ifm-transition-fast) ease;
+}
+
+.cardContainer.cardContainerLink:hover {
+  /* box-shadow: var(--ifm-global-shadow-md); */
+  box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2);
+}
+html[data-theme='dark'] .cardContainer.cardContainerLink:hover {
+  --ifm-card-background-color: #2d2d2d; /* original, non-hovered color is #242526 */
+}
+
+.cardContainer:not(.cardContainerLink) {
+  cursor: not-allowed;
+}
+
+.cardTitle {
+  font-size: 1.2rem;
+  min-height: 1.2rem;
+}
+
+.cardDescription {
+  font-size: 0.8rem;
+  min-height: 0.8rem;
+}

package/src/theme/DocCardList/index.tsx

@@ -0,0 +1,27 @@
+/**
+ * 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 DocCard from '@theme/DocCard';
+import {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+export default function DocCardList({
+  items,
+}: {
+  items: PropSidebarItem[];
+}): JSX.Element {
+  return (
+    <div className="row">
+      {items.map((item, index) => (
+        <article key={index} className="col col--6">
+          <DocCard item={item} />
+        </article>
+      ))}
+    </div>
+  );
+}

package/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -0,0 +1,53 @@
+/**
+ * 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 {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+import type {Props} from '@theme/DocCategoryGeneratedIndexPage';
+import DocCardList from '@theme/DocCardList';
+import DocPaginator from '@theme/DocPaginator';
+import Seo from '@theme/Seo';
+import DocVersionBanner from '@theme/DocVersionBanner';
+import DocVersionBadge from '@theme/DocVersionBadge';
+import {MainHeading} from '@theme/Heading';
+
+import styles from './styles.module.css';
+
+export default function DocCategoryGeneratedIndexPage({
+  categoryGeneratedIndex,
+}: Props): JSX.Element {
+  const category = useCurrentSidebarCategory();
+  return (
+    <>
+      <Seo
+        title={categoryGeneratedIndex.title}
+        description={categoryGeneratedIndex.description}
+      />
+      <div className={styles.generatedIndexPage}>
+        <DocVersionBanner />
+        <DocVersionBadge />
+        <header>
+          <MainHeading className={styles.title}>
+            {categoryGeneratedIndex.title}
+          </MainHeading>
+          {categoryGeneratedIndex.description && (
+            <p>{categoryGeneratedIndex.description}</p>
+          )}
+        </header>
+        <main className="margin-top--lg">
+          <DocCardList items={category.items} />
+        </main>
+        <footer className="margin-top--lg">
+          <DocPaginator
+            previous={categoryGeneratedIndex.navigation.previous}
+            next={categoryGeneratedIndex.navigation.next}
+          />
+        </footer>
+      </div>
+    </>
+  );
+}

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

@@ -0,0 +1,18 @@
+/**
+ * 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) {
+  .generatedIndexPage {
+    max-width: 75% !important;
+  }
+}
+
+/* Duplicated from .markdown h1 */
+.title {
+  --ifm-h1-font-size: 3rem;
+  margin-bottom: calc(1.25 * var(--ifm-leading));
+}

package/src/theme/DocItem/index.tsx

@@ -10,6 +10,7 @@ import clsx from 'clsx';
 import useWindowSize from '@theme/hooks/useWindowSize';
 import DocPaginator from '@theme/DocPaginator';
 import DocVersionBanner from '@theme/DocVersionBanner';
+import DocVersionBadge from '@theme/DocVersionBadge';
 import Seo from '@theme/Seo';
 import type {Props} from '@theme/DocItem';
 import DocItemFooter from '@theme/DocItemFooter';
@@ -20,7 +21,7 @@ import styles from './styles.module.css';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 
 export default function DocItem(props: Props): JSX.Element {
-  const {content: DocContent, versionMetadata} = props;
+  const {content: DocContent} = props;
   const {metadata, frontMatter} = DocContent;
   const {
     image,
@@ -55,18 +56,10 @@ export default function DocItem(props: Props): JSX.Element {
           className={clsx('col', {
             [styles.docItemCol]: !hideTableOfContents,
           })}>
-          <DocVersionBanner versionMetadata={versionMetadata} />
+          <DocVersionBanner />
           <div className={styles.docItemContainer}>
             <article>
-              {versionMetadata.badge && (
-                <span
-                  className={clsx(
-                    ThemeClassNames.docs.docVersionBadge,
-                    'badge badge--secondary',
-                  )}>
-                  Version: {versionMetadata.label}
-                </span>
-              )}
+              <DocVersionBadge />
 
               {canRenderTOC && (
                 <TOCCollapsible
@@ -95,7 +88,7 @@ export default function DocItem(props: Props): JSX.Element {
               <DocItemFooter {...props} />
             </article>
 
-            <DocPaginator metadata={metadata} />
+            <DocPaginator previous={metadata.previous} next={metadata.next} />
           </div>
         </div>
         {renderTocDesktop && (

package/src/theme/DocPage/index.tsx

@@ -23,27 +23,30 @@ import {translate} from '@docusaurus/Translate';
 
 import clsx from 'clsx';
 import styles from './styles.module.css';
-import {ThemeClassNames, docVersionSearchTag} from '@docusaurus/theme-common';
+import {
+  ThemeClassNames,
+  docVersionSearchTag,
+  DocsSidebarProvider,
+  useDocsSidebar,
+  DocsVersionProvider,
+} from '@docusaurus/theme-common';
 import Head from '@docusaurus/Head';
 
 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 sidebarName = currentDocRoute.sidebar;
-  const sidebar = sidebarName
-    ? versionMetadata.docsSidebars[sidebarName]
-    : undefined;
-
   const [hiddenSidebarContainer, setHiddenSidebarContainer] = useState(false);
   const [hiddenSidebar, setHiddenSidebar] = useState(false);
   const toggleSidebar = useCallback(() => {
@@ -150,17 +153,30 @@ function DocPage(props: Props): JSX.Element {
   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 (
     <>
       <Head>
         {/* TODO we should add a core addRoute({htmlClassName}) generic plugin option */}
         <html className={versionMetadata.className} />
       </Head>
-      <DocPageContent
-        currentDocRoute={currentDocRoute}
-        versionMetadata={versionMetadata}>
-        {renderRoutes(docRoutes, {versionMetadata})}
-      </DocPageContent>
+      <DocsVersionProvider version={versionMetadata}>
+        <DocsSidebarProvider sidebar={sidebar}>
+          <DocPageContent
+            currentDocRoute={currentDocRoute}
+            versionMetadata={versionMetadata}
+            sidebarName={sidebarName}>
+            {renderRoutes(docRoutes, {versionMetadata})}
+          </DocPageContent>
+        </DocsSidebarProvider>
+      </DocsVersionProvider>
     </>
   );
 }

package/src/theme/DocPaginator/index.tsx

@@ -8,10 +8,10 @@
 import React from 'react';
 import Link from '@docusaurus/Link';
 import Translate, {translate} from '@docusaurus/Translate';
-import type {Props} from '@theme/DocPaginator';
+import type {PropNavigation} from '@docusaurus/plugin-content-docs';
 
-function DocPaginator(props: Props): JSX.Element {
-  const {metadata} = props;
+function DocPaginator(props: PropNavigation): JSX.Element {
+  const {previous, next} = props;
 
   return (
     <nav
@@ -22,10 +22,8 @@ function DocPaginator(props: Props): JSX.Element {
         description: 'The ARIA label for the docs pagination',
       })}>
       <div className="pagination-nav__item">
-        {metadata.previous && (
-          <Link
-            className="pagination-nav__link"
-            to={metadata.previous.permalink}>
+        {previous && (
+          <Link className="pagination-nav__link" to={previous.permalink}>
             <div className="pagination-nav__sublabel">
               <Translate
                 id="theme.docs.paginator.previous"
@@ -34,14 +32,14 @@ function DocPaginator(props: Props): JSX.Element {
               </Translate>
             </div>
             <div className="pagination-nav__label">
-              &laquo; {metadata.previous.title}
+              &laquo; {previous.title}
             </div>
           </Link>
         )}
       </div>
       <div className="pagination-nav__item pagination-nav__item--next">
-        {metadata.next && (
-          <Link className="pagination-nav__link" to={metadata.next.permalink}>
+        {next && (
+          <Link className="pagination-nav__link" to={next.permalink}>
             <div className="pagination-nav__sublabel">
               <Translate
                 id="theme.docs.paginator.next"
@@ -49,9 +47,7 @@ function DocPaginator(props: Props): JSX.Element {
                 Next
               </Translate>
             </div>
-            <div className="pagination-nav__label">
-              {metadata.next.title} &raquo;
-            </div>
+            <div className="pagination-nav__label">{next.title} &raquo;</div>
           </Link>
         )}
       </div>

package/src/theme/DocSidebar/index.tsx

@@ -100,7 +100,15 @@ const DocSidebarMobileSecondaryMenu: MobileSecondaryMenuComponent<Props> = ({
     <DocSidebarItems
       items={sidebar}
       activePath={path}
-      onItemClick={() => toggleSidebar()}
+      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>

package/src/theme/DocSidebarItem/index.tsx

@@ -5,17 +5,19 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useEffect, memo} from 'react';
+import React, {useEffect, memo, useMemo} from 'react';
 import clsx from 'clsx';
 import {
-  isSamePath,
+  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';
@@ -25,21 +27,7 @@ import type {
 } from '@docusaurus/plugin-content-docs';
 
 import styles from './styles.module.css';
-
-const isActiveSidebarItem = (
-  item: Props['item'],
-  activePath: string,
-): boolean => {
-  if (item.type === 'link') {
-    return isSamePath(item.href, activePath);
-  }
-  if (item.type === 'category') {
-    return item.items.some((subItem) =>
-      isActiveSidebarItem(subItem, activePath),
-    );
-  }
-  return false;
-};
+import useIsBrowser from '@docusaurus/useIsBrowser';
 
 // Optimize sidebar at each "level"
 // TODO this item should probably not receive the "activePath" props
@@ -93,6 +81,28 @@ function useAutoExpandActiveCategory({
   }, [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,
@@ -100,7 +110,8 @@ function DocSidebarItemCategory({
   level,
   ...props
 }: Props & {item: PropSidebarItemCategory}) {
-  const {items, label, collapsible, className} = item;
+  const {items, label, collapsible, className, href} = item;
+  const hrefWithSSRFallback = useCategoryHrefWithSSRFallback(item);
 
   const isActive = isActiveSidebarItem(item, activePath);
 
@@ -128,25 +139,53 @@ function DocSidebarItemCategory({
         },
         className,
       )}>
-      {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
-      <a
-        className={clsx('menu__link', {
-          'menu__link--sublist': collapsible,
-          'menu__link--active': collapsible && isActive,
-          [styles.menuLinkText]: !collapsible,
-        })}
-        onClick={
-          collapsible
-            ? (e) => {
-                e.preventDefault();
-                toggleCollapsed();
-              }
-            : undefined
-        }
-        href={collapsible ? '#' : undefined}
-        {...props}>
-        {label}
-      </a>
+      <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
@@ -186,7 +225,7 @@ function DocSidebarItemLink({
         aria-current={isActive ? 'page' : undefined}
         to={href}
         {...(isInternalUrl(href) && {
-          onClick: onItemClick,
+          onClick: onItemClick ? () => onItemClick(item) : undefined,
         })}
         {...props}>
         {isInternalUrl(href) ? (

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

@@ -12,4 +12,8 @@
   .menuLinkText:hover {
     background: none;
   }
+
+  .menuLinkText.hasHref {
+    cursor: pointer;
+  }
 }