@docusaurus/theme-classic 2.0.0-beta.12faed89d → 2.0.0-beta.14

package/src/theme/DocSidebarItem/index.tsx

@@ -5,46 +5,35 @@
  * 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';
 import type {
   PropSidebarItemCategory,
   PropSidebarItemLink,
-} from '@docusaurus/plugin-content-docs-types';
+} from '@docusaurus/plugin-content-docs';
 
 import styles from './styles.module.css';
-
-const isActiveSidebarItem = (item: Props['item'], activePath: string) => {
-  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
 // TODO this triggers whole sidebar re-renders on navigation
-export const DocSidebarItems = memo(function DocSidebarItems({
-  items,
-  ...props
-}: DocSidebarItemsProps): JSX.Element {
-  return (
+export const DocSidebarItems = memo(
+  ({items, ...props}: DocSidebarItemsProps): JSX.Element => (
     <>
       {items.map((item, index) => (
         <DocSidebarItem
@@ -54,8 +43,8 @@ export const DocSidebarItems = memo(function DocSidebarItems({
         />
       ))}
     </>
-  );
-});
+  ),
+);
 
 export default function DocSidebarItem({
   item,
@@ -89,17 +78,40 @@ function useAutoExpandActiveCategory({
     if (justBecameActive && collapsed) {
       setCollapsed(false);
     }
-  }, [isActive, wasActive, collapsed]);
+  }, [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,
-  collapsible = true,
   activePath,
+  level,
   ...props
 }: Props & {item: PropSidebarItemCategory}) {
-  const {items, label} = item;
+  const {items, label, collapsible, className, href} = item;
+  const hrefWithSSRFallback = useCategoryHrefWithSSRFallback(item);
 
   const isActive = isActiveSidebarItem(item, activePath);
 
@@ -110,7 +122,7 @@ function DocSidebarItemCategory({
       if (!collapsible) {
         return false;
       }
-      return isActive ? false : item.collapsed ?? true;
+      return isActive ? false : item.collapsed;
     },
   });
 
@@ -118,29 +130,70 @@ function DocSidebarItemCategory({
 
   return (
     <li
-      className={clsx('menu__list-item', {
-        'menu__list-item--collapsed': collapsed,
-      })}>
-      {/* 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 ? toggleCollapsed : undefined}
-        href={collapsible ? '#' : undefined}
-        {...props}>
-        {label}
-      </a>
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemCategory,
+        ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
+        'menu__list-item',
+        {
+          'menu__list-item--collapsed': collapsed,
+        },
+        className,
+      )}>
+      <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 as="ul" className="menu__list" collapsed={collapsed}>
+      <Collapsible lazy as="ul" className="menu__list" collapsed={collapsed}>
         <DocSidebarItems
           items={items}
           tabIndex={collapsed ? -1 : 0}
           onItemClick={onItemClick}
-          collapsible={collapsible}
           activePath={activePath}
+          level={level + 1}
         />
       </Collapsible>
     </li>
@@ -151,22 +204,28 @@ function DocSidebarItemLink({
   item,
   onItemClick,
   activePath,
-  collapsible: _collapsible,
+  level,
   ...props
 }: Props & {item: PropSidebarItemLink}) {
-  const {href, label} = item;
+  const {href, label, className} = item;
   const isActive = isActiveSidebarItem(item, activePath);
   return (
-    <li className="menu__list-item" key={label}>
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        'menu__list-item',
+        className,
+      )}
+      key={label}>
       <Link
         className={clsx('menu__link', {
           'menu__link--active': isActive,
         })}
+        aria-current={isActive ? 'page' : undefined}
         to={href}
         {...(isInternalUrl(href) && {
-          isNavLink: true,
-          exact: true,
-          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;
+  }
 }

package/src/theme/DocTagDocListPage/index.tsx

@@ -0,0 +1,89 @@
+/**
+ * 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 Layout from '@theme/Layout';
+import Link from '@docusaurus/Link';
+import {ThemeClassNames, usePluralForm} from '@docusaurus/theme-common';
+import type {PropTagDocListDoc} from '@docusaurus/plugin-content-docs';
+import Translate, {translate} from '@docusaurus/Translate';
+import type {Props} from '@theme/DocTagDocListPage';
+
+// Very simple pluralization: probably good enough for now
+function useNDocsTaggedPlural() {
+  const {selectMessage} = usePluralForm();
+  return (count: number) =>
+    selectMessage(
+      count,
+      translate(
+        {
+          id: 'theme.docs.tagDocListPageTitle.nDocsTagged',
+          description:
+            'Pluralized label for "{count} docs tagged". Use as much plural forms (separated by "|") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)',
+          message: 'One doc tagged|{count} docs tagged',
+        },
+        {count},
+      ),
+    );
+}
+
+function DocItem({doc}: {doc: PropTagDocListDoc}): JSX.Element {
+  return (
+    <article className="margin-vert--lg">
+      <Link to={doc.permalink}>
+        <h2>{doc.title}</h2>
+      </Link>
+      {doc.description && <p>{doc.description}</p>}
+    </article>
+  );
+}
+
+export default function DocTagDocListPage({tag}: Props): JSX.Element {
+  const nDocsTaggedPlural = useNDocsTaggedPlural();
+  const title = translate(
+    {
+      id: 'theme.docs.tagDocListPageTitle',
+      description: 'The title of the page for a docs tag',
+      message: '{nDocsTagged} with "{tagName}"',
+    },
+    {nDocsTagged: nDocsTaggedPlural(tag.docs.length), tagName: tag.name},
+  );
+
+  return (
+    <Layout
+      title={title}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
+      pageClassName={ThemeClassNames.page.docsTagDocListPage}
+      searchMetadata={{
+        // assign unique search tag to exclude this page from search results!
+        tag: 'doc_tag_doc_list',
+      }}>
+      <div className="container margin-vert--lg">
+        <div className="row">
+          <main className="col col--8 col--offset-2">
+            <header className="margin-bottom--xl">
+              <h1>{title}</h1>
+              <Link href={tag.allTagsPath}>
+                <Translate
+                  id="theme.tags.tagsPageLink"
+                  description="The label of the link targeting the tag list page">
+                  View All Tags
+                </Translate>
+              </Link>
+            </header>
+            <section className="margin-vert--lg">
+              {tag.docs.map((doc) => (
+                <DocItem key={doc.id} doc={doc} />
+              ))}
+            </section>
+          </main>
+        </div>
+      </div>
+    </Layout>
+  );
+}

package/src/theme/DocTagsListPage/index.tsx

@@ -0,0 +1,41 @@
+/**
+ * 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 Layout from '@theme/Layout';
+import {
+  ThemeClassNames,
+  translateTagsPageTitle,
+} from '@docusaurus/theme-common';
+import TagsListByLetter from '@theme/TagsListByLetter';
+import type {Props} from '@theme/DocTagsListPage';
+
+function DocTagsListPage({tags}: Props): JSX.Element {
+  const title = translateTagsPageTitle();
+  return (
+    <Layout
+      title={title}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
+      pageClassName={ThemeClassNames.page.docsTagsListPage}
+      searchMetadata={{
+        // assign unique search tag to exclude this page from search results!
+        tag: 'doc_tags_list',
+      }}>
+      <div className="container margin-vert--lg">
+        <div className="row">
+          <main className="col col--8 col--offset-2">
+            <h1>{title}</h1>
+            <TagsListByLetter tags={tags} />
+          </main>
+        </div>
+      </div>
+    </Layout>
+  );
+}
+
+export default DocTagsListPage;

package/src/theme/DocVersionBadge/index.tsx

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

package/src/theme/DocVersionBanner/index.tsx

@@ -9,14 +9,27 @@ import React, {ComponentType} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Link from '@docusaurus/Link';
 import Translate from '@docusaurus/Translate';
-import {useActivePlugin, useDocVersionSuggestions} from '@theme/hooks/useDocs';
-import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+import {
+  useActivePlugin,
+  useDocVersionSuggestions,
+  GlobalVersion,
+} from '@theme/hooks/useDocs';
+import {
+  ThemeClassNames,
+  useDocsPreferredVersion,
+  useDocsVersion,
+} from '@docusaurus/theme-common';
 
 import type {Props} from '@theme/DocVersionBanner';
+import clsx from 'clsx';
+import type {
+  VersionBanner,
+  PropVersionMetadata,
+} from '@docusaurus/plugin-content-docs';
 
 type BannerLabelComponentProps = {
   siteTitle: string;
-  versionMetadata: Props['versionMetadata'];
+  versionMetadata: PropVersionMetadata;
 };
 
 function UnreleasedVersionLabel({
@@ -58,7 +71,7 @@ function UnmaintainedVersionLabel({
 }
 
 const BannerLabelComponents: Record<
-  Props['versionMetadata']['banner'],
+  VersionBanner,
   ComponentType<BannerLabelComponentProps>
 > = {
   unreleased: UnreleasedVersionLabel,
@@ -67,7 +80,7 @@ const BannerLabelComponents: Record<
 
 function BannerLabel(props: BannerLabelComponentProps) {
   const BannerLabelComponent =
-    BannerLabelComponents[props.versionMetadata.banner];
+    BannerLabelComponents[props.versionMetadata.banner!];
   return <BannerLabelComponent {...props} />;
 }
 
@@ -105,21 +118,24 @@ function LatestVersionSuggestionLabel({
   );
 }
 
-function DocVersionBannerEnabled({versionMetadata}: Props): JSX.Element {
+function DocVersionBannerEnabled({
+  className,
+  versionMetadata,
+}: Props & {
+  versionMetadata: PropVersionMetadata;
+}): JSX.Element {
   const {
     siteConfig: {title: siteTitle},
   } = useDocusaurusContext();
-  const {pluginId} = useActivePlugin({failfast: true});
+  const {pluginId} = useActivePlugin({failfast: true})!;
 
-  const getVersionMainDoc = (version) =>
-    version.docs.find((doc) => doc.id === version.mainDocId);
+  const getVersionMainDoc = (version: GlobalVersion) =>
+    version.docs.find((doc) => doc.id === version.mainDocId)!;
 
   const {savePreferredVersionName} = useDocsPreferredVersion(pluginId);
 
-  const {
-    latestDocSuggestion,
-    latestVersionSuggestion,
-  } = useDocVersionSuggestions(pluginId);
+  const {latestDocSuggestion, latestVersionSuggestion} =
+    useDocVersionSuggestions(pluginId);
 
   // try to link to same doc in latest version (not always possible)
   // fallback to main doc of latest version
@@ -127,7 +143,13 @@ function DocVersionBannerEnabled({versionMetadata}: Props): JSX.Element {
     latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion);
 
   return (
-    <div className="alert alert--warning margin-bottom--md" role="alert">
+    <div
+      className={clsx(
+        className,
+        ThemeClassNames.docs.docVersionBanner,
+        'alert alert--warning margin-bottom--md',
+      )}
+      role="alert">
       <div>
         <BannerLabel siteTitle={siteTitle} versionMetadata={versionMetadata} />
       </div>
@@ -142,12 +164,17 @@ function DocVersionBannerEnabled({versionMetadata}: Props): JSX.Element {
   );
 }
 
-function DocVersionBanner({versionMetadata}: Props): JSX.Element {
-  if (versionMetadata.banner === 'none') {
-    return <></>;
-  } else {
-    return <DocVersionBannerEnabled versionMetadata={versionMetadata} />;
+export default function DocVersionBanner({
+  className,
+}: Props): JSX.Element | null {
+  const versionMetadata = useDocsVersion();
+  if (versionMetadata.banner) {
+    return (
+      <DocVersionBannerEnabled
+        className={className}
+        versionMetadata={versionMetadata}
+      />
+    );
   }
+  return null;
 }
-
-export default DocVersionBanner;

package/src/theme/EditThisPage/index.tsx

@@ -10,10 +10,15 @@ import Translate from '@docusaurus/Translate';
 
 import type {Props} from '@theme/EditThisPage';
 import IconEdit from '@theme/IconEdit';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 export default function EditThisPage({editUrl}: Props): JSX.Element {
   return (
-    <a href={editUrl} target="_blank" rel="noreferrer noopener">
+    <a
+      href={editUrl}
+      target="_blank"
+      rel="noreferrer noopener"
+      className={ThemeClassNames.common.editThisPage}>
       <IconEdit />
       <Translate
         id="theme.common.editThisPage"

package/src/theme/ErrorPageContent.tsx

@@ -0,0 +1,41 @@
+/**
+ * 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 Translate from '@docusaurus/Translate';
+import type {Props} from '@theme/Error';
+
+export default function ErrorPageContent({
+  error,
+  tryAgain,
+}: Props): JSX.Element {
+  return (
+    <main className="container margin-vert--xl">
+      <div className="row">
+        <div className="col col--6 col--offset-3">
+          <h1 className="hero__title">
+            <Translate
+              id="theme.ErrorPageContent.title"
+              description="The title of the fallback page when the page crashed">
+              This page crashed.
+            </Translate>
+          </h1>
+          <p>{error.message}</p>
+          <div>
+            <button type="button" onClick={tryAgain}>
+              <Translate
+                id="theme.ErrorPageContent.tryAgain"
+                description="The label of the button to try again when the page crashed">
+                Try again
+              </Translate>
+            </button>
+          </div>
+        </div>
+      </div>
+    </main>
+  );
+}