@docusaurus/theme-classic 0.0.0-4238 → 0.0.0-4243

package/lib-next/index.js

@@ -123,7 +123,11 @@ export default function docusaurusThemeClassic(
       getTranslationFiles({
         themeConfig,
       }),
-    translateThemeConfig,
+    translateThemeConfig: (params) =>
+      translateThemeConfig({
+        themeConfig: params.themeConfig,
+        translationFiles: params.translationFiles,
+      }),
 
     getDefaultCodeTranslationMessages() {
       return readDefaultCodeTranslationMessages({

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

@@ -0,0 +1,80 @@
+/**
+ * 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 Link from '@docusaurus/Link';
+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}) {
+  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}) {
+  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}) {
+  const href = findFirstCategoryLink(item);
+  return (
+    <CardLayout
+      href={href}
+      icon="🗃️"
+      title={item.label}
+      description={`${item.items.length} items`}
+    />
+  );
+}
+
+function CardLink({item}) {
+  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}) {
+  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/lib-next/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/lib-next/theme/DocCardList/index.js

@@ -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.
+ */
+import React from 'react';
+import DocCard from '@theme/DocCard';
+export default function DocCardList({items}) {
+  return (
+    <div className="row">
+      {items.map((item, index) => (
+        <article key={index} className="col col--6">
+          <DocCard item={item} />
+        </article>
+      ))}
+    </div>
+  );
+}

package/lib-next/theme/DocCategoryGeneratedIndexPage/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 {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+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,
+}) {
+  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/lib-next/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/lib-next/theme/DocItem/index.js

@@ -9,6 +9,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 DocItemFooter from '@theme/DocItemFooter';
 import TOC from '@theme/TOC';
@@ -17,7 +18,7 @@ import {MainHeading} from '@theme/Heading';
 import styles from './styles.module.css';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 export default function DocItem(props) {
-  const {content: DocContent, versionMetadata} = props;
+  const {content: DocContent} = props;
   const {metadata, frontMatter} = DocContent;
   const {
     image,
@@ -54,18 +55,10 @@ export default function DocItem(props) {
           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
@@ -94,7 +87,7 @@ export default function DocItem(props) {
               <DocItemFooter {...props} />
             </article>
 
-            <DocPaginator metadata={metadata} />
+            <DocPaginator previous={metadata.previous} next={metadata.next} />
           </div>
         </div>
         {renderTocDesktop && (

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

@@ -17,15 +17,23 @@ import {matchPath} from '@docusaurus/router';
 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';
 
-function DocPageContent({currentDocRoute, versionMetadata, children}) {
+function DocPageContent({
+  currentDocRoute,
+  versionMetadata,
+  children,
+  sidebarName,
+}) {
+  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(() => {
@@ -131,21 +139,30 @@ function DocPage(props) {
 
   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/lib-next/theme/DocPaginator/index.js

@@ -9,7 +9,7 @@ import Link from '@docusaurus/Link';
 import Translate, {translate} from '@docusaurus/Translate';
 
 function DocPaginator(props) {
-  const {metadata} = props;
+  const {previous, next} = props;
   return (
     <nav
       className="pagination-nav docusaurus-mt-lg"
@@ -19,10 +19,8 @@ function DocPaginator(props) {
         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"
@@ -31,14 +29,14 @@ function DocPaginator(props) {
               </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"
@@ -46,9 +44,7 @@ function DocPaginator(props) {
                 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/lib-next/theme/DocSidebar/index.js

@@ -89,7 +89,16 @@ const DocSidebarMobileSecondaryMenu = ({toggleSidebar, sidebar, path}) => (
     <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/lib-next/theme/DocSidebarItem/index.js

@@ -4,33 +4,22 @@
  * 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} 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 styles from './styles.module.css';
-
-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"
+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
 
@@ -69,6 +58,26 @@ function useAutoExpandActiveCategory({isActive, collapsed, setCollapsed}) {
       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({
@@ -78,7 +87,8 @@ function DocSidebarItemCategory({
   level,
   ...props
 }) {
-  const {items, label, collapsible, className} = item;
+  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
@@ -107,25 +117,56 @@ 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
@@ -159,7 +200,7 @@ function DocSidebarItemLink({item, onItemClick, activePath, level, ...props}) {
         aria-current={isActive ? 'page' : undefined}
         to={href}
         {...(isInternalUrl(href) && {
-          onClick: onItemClick,
+          onClick: onItemClick ? () => onItemClick(item) : undefined,
         })}
         {...props}>
         {isInternalUrl(href) ? (

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

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

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

@@ -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 {ThemeClassNames, useDocsVersion} from '@docusaurus/theme-common';
+import clsx from 'clsx';
+export default function DocVersionBadge({className}) {
+  const versionMetadata = useDocsVersion();
+
+  if (versionMetadata.badge) {
+    return (
+      <span
+        className={clsx(
+          className,
+          ThemeClassNames.docs.docVersionBadge,
+          'badge badge--secondary',
+        )}>
+        Version: {versionMetadata.label}
+      </span>
+    );
+  }
+
+  return null;
+}

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

@@ -12,6 +12,7 @@ import {useActivePlugin, useDocVersionSuggestions} from '@theme/hooks/useDocs';
 import {
   ThemeClassNames,
   useDocsPreferredVersion,
+  useDocsVersion,
 } from '@docusaurus/theme-common';
 import clsx from 'clsx';
 
@@ -84,7 +85,7 @@ function LatestVersionSuggestionLabel({versionLabel, to, onClick}) {
   );
 }
 
-function DocVersionBannerEnabled({versionMetadata}) {
+function DocVersionBannerEnabled({className, versionMetadata}) {
   const {
     siteConfig: {title: siteTitle},
   } = useDocusaurusContext();
@@ -105,6 +106,7 @@ function DocVersionBannerEnabled({versionMetadata}) {
   return (
     <div
       className={clsx(
+        className,
         ThemeClassNames.docs.docVersionBanner,
         'alert alert--warning margin-bottom--md',
       )}
@@ -123,12 +125,17 @@ function DocVersionBannerEnabled({versionMetadata}) {
   );
 }
 
-function DocVersionBanner({versionMetadata}) {
+export default function DocVersionBanner({className}) {
+  const versionMetadata = useDocsVersion();
+
   if (versionMetadata.banner) {
-    return <DocVersionBannerEnabled versionMetadata={versionMetadata} />;
+    return (
+      <DocVersionBannerEnabled
+        className={className}
+        versionMetadata={versionMetadata}
+      />
+    );
   }
 
   return null;
 }
-
-export default DocVersionBanner;

package/lib-next/theme-classic.d.ts

@@ -107,11 +107,12 @@ declare module '@theme/CodeBlock' {
 }
 
 declare module '@theme/DocPaginator' {
+  import type {PropNavigation} from '@docusaurus/plugin-content-docs';
+
   type PageInfo = {readonly permalink: string; readonly title: string};
 
-  export interface Props {
-    readonly metadata: {readonly previous?: PageInfo; readonly next?: PageInfo};
-  }
+  // May be simpler to provide a {navigation: PropNavigation} prop?
+  export interface Props extends PropNavigation {}
 
   const DocPaginator: (props: Props) => JSX.Element;
   export default DocPaginator;
@@ -138,7 +139,7 @@ declare module '@theme/DocSidebarItem' {
 
   type DocSidebarPropsBase = {
     readonly activePath: string;
-    readonly onItemClick?: () => void;
+    readonly onItemClick?: (item: PropSidebarItem) => void;
     readonly level: number;
     readonly tabIndex?: number;
   };