@docusaurus/theme-classic 2.0.0-beta.15d451942 → 2.0.0-beta.16

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

@@ -0,0 +1,264 @@
+/**
+ * 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, {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 isInternalUrl from '@docusaurus/isInternalUrl';
+import {translate} from '@docusaurus/Translate';
+import IconExternalLink from '@theme/IconExternalLink';
+import DocSidebarItems from '@theme/DocSidebarItems';
+import styles from './styles.module.css';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+export default function DocSidebarItem({item, ...props}) {
+  switch (item.type) {
+    case 'category':
+      return <DocSidebarItemCategory item={item} {...props} />;
+
+    case 'html':
+      return <DocSidebarItemHtml item={item} {...props} />;
+
+    case 'link':
+    default:
+      return <DocSidebarItemLink item={item} {...props} />;
+  }
+} // If we navigate to a category and it becomes active, it should automatically
+// expand itself
+
+function useAutoExpandActiveCategory({isActive, collapsed, setCollapsed}) {
+  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) {
+  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,
+  activePath,
+  level,
+  index,
+  ...props
+}) {
+  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 = !collapsed) {
+    setExpandedItem(toCollapsed ? null : index);
+    setCollapsed(toCollapsed);
+  }
+
+  const {autoCollapseSidebarCategories} = useThemeConfig();
+  useEffect(() => {
+    if (
+      collapsible &&
+      expandedItem &&
+      expandedItem !== index &&
+      autoCollapseSidebarCategories
+    ) {
+      setCollapsed(true);
+    }
+  }, [
+    collapsible,
+    expandedItem,
+    index,
+    setCollapsed,
+    autoCollapseSidebarCategories,
+  ]);
+  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 && !href,
+            'menu__link--active': isActive,
+          })}
+          onClick={
+            collapsible
+              ? (e) => {
+                  onItemClick?.(item);
+
+                  if (href) {
+                    updateCollapsed(false);
+                  } else {
+                    e.preventDefault();
+                    updateCollapsed();
+                  }
+                }
+              : () => {
+                  onItemClick?.(item);
+                }
+          }
+          aria-current={isCurrentPage ? 'page' : undefined}
+          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();
+              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>
+  );
+}
+
+function DocSidebarItemHtml({item, level, index}) {
+  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,
+      }}
+    />
+  );
+}
+
+function DocSidebarItemLink({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}) {
+  const {href, label, className} = item;
+  const isActive = isActiveSidebarItem(item, activePath);
+  return (
+    <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) && {
+          onClick: onItemClick ? () => onItemClick(item) : undefined,
+        })}
+        {...props}>
+        {isInternalUrl(href) ? (
+          label
+        ) : (
+          <span>
+            {label}
+            <IconExternalLink />
+          </span>
+        )}
+      </Link>
+    </li>
+  );
+}

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

@@ -0,0 +1,13 @@
+/**
+ * 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) {
+  .menuHtmlItem {
+    padding: var(--ifm-menu-link-padding-vertical)
+      var(--ifm-menu-link-padding-horizontal);
+  }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * 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, {memo} from 'react';
+import DocSidebarItem from '@theme/DocSidebarItem';
+import {DocSidebarItemsExpandedStateProvider} from '@docusaurus/theme-common';
+
+// TODO this item should probably not receive the "activePath" props
+// TODO this triggers whole sidebar re-renders on navigation
+function DocSidebarItems({items, ...props}) {
+  return (
+    <DocSidebarItemsExpandedStateProvider>
+      {items.map((item, index) => (
+        <DocSidebarItem
+          key={index} // sidebar is static, the index does not change
+          item={item}
+          index={index}
+          {...props}
+        />
+      ))}
+    </DocSidebarItemsExpandedStateProvider>
+  );
+} // Optimize sidebar at each "level"
+
+export default memo(DocSidebarItems);

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

@@ -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 Translate, {translate} from '@docusaurus/Translate';
+
+// Very simple pluralization: probably good enough for now
+function useNDocsTaggedPlural() {
+  const {selectMessage} = usePluralForm();
+  return (count) =>
+    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}) {
+  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}) {
+  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/lib-next/theme/DocTagsListPage/index.js

@@ -0,0 +1,35 @@
+/**
+ * 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';
+export default function DocTagsListPage({tags}) {
+  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>
+  );
+}

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

@@ -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 Translate from '@docusaurus/Translate';
+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',
+        )}>
+        <Translate
+          id="theme.docs.versionBadge.label"
+          values={{
+            versionLabel: versionMetadata.label,
+          }}>
+          {'Version: {versionLabel}'}
+        </Translate>
+      </span>
+    );
+  }
+
+  return null;
+}

package/lib-next/theme/{DocVersionSuggestions → DocVersionBanner}/index.js

@@ -10,19 +10,23 @@ import Link from '@docusaurus/Link';
 import Translate from '@docusaurus/Translate';
 import {
   useActivePlugin,
-  useActiveVersion,
   useDocVersionSuggestions,
-} from '@theme/hooks/useDocs';
-import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+} from '@docusaurus/plugin-content-docs/client';
+import {
+  ThemeClassNames,
+  useDocsPreferredVersion,
+  useDocsVersion,
+} from '@docusaurus/theme-common';
+import clsx from 'clsx';
 
-function UnreleasedVersionLabel({siteTitle, versionLabel}) {
+function UnreleasedVersionLabel({siteTitle, versionMetadata}) {
   return (
     <Translate
       id="theme.docs.versions.unreleasedVersionLabel"
       description="The label used to tell the user that he's browsing an unreleased doc version"
       values={{
         siteTitle,
-        versionLabel: <strong>{versionLabel}</strong>,
+        versionLabel: <b>{versionMetadata.label}</b>,
       }}>
       {
         'This is unreleased documentation for {siteTitle} {versionLabel} version.'
@@ -31,14 +35,14 @@ function UnreleasedVersionLabel({siteTitle, versionLabel}) {
   );
 }
 
-function UnmaintainedVersionLabel({siteTitle, versionLabel}) {
+function UnmaintainedVersionLabel({siteTitle, versionMetadata}) {
   return (
     <Translate
       id="theme.docs.versions.unmaintainedVersionLabel"
       description="The label used to tell the user that he's browsing an unmaintained doc version"
       values={{
         siteTitle,
-        versionLabel: <strong>{versionLabel}</strong>,
+        versionLabel: <b>{versionMetadata.label}</b>,
       }}>
       {
         'This is documentation for {siteTitle} {versionLabel}, which is no longer actively maintained.'
@@ -47,15 +51,26 @@ function UnmaintainedVersionLabel({siteTitle, versionLabel}) {
   );
 }
 
+const BannerLabelComponents = {
+  unreleased: UnreleasedVersionLabel,
+  unmaintained: UnmaintainedVersionLabel,
+};
+
+function BannerLabel(props) {
+  const BannerLabelComponent =
+    BannerLabelComponents[props.versionMetadata.banner];
+  return <BannerLabelComponent {...props} />;
+}
+
 function LatestVersionSuggestionLabel({versionLabel, to, onClick}) {
   return (
     <Translate
       id="theme.docs.versions.latestVersionSuggestionLabel"
-      description="The label userd to tell the user that he's browsing an unmaintained doc version"
+      description="The label used to tell the user to check the latest version"
       values={{
         versionLabel,
         latestVersionLink: (
-          <strong>
+          <b>
             <Link to={to} onClick={onClick}>
               <Translate
                 id="theme.docs.versions.latestVersionLinkLabel"
@@ -63,7 +78,7 @@ function LatestVersionSuggestionLabel({versionLabel, to, onClick}) {
                 latest version
               </Translate>
             </Link>
-          </strong>
+          </b>
         ),
       }}>
       {
@@ -73,44 +88,34 @@ function LatestVersionSuggestionLabel({versionLabel, to, onClick}) {
   );
 }
 
-const getVersionMainDoc = (version) =>
-  version.docs.find((doc) => doc.id === version.mainDocId);
-
-function DocVersionSuggestions() {
+function DocVersionBannerEnabled({className, versionMetadata}) {
   const {
     siteConfig: {title: siteTitle},
   } = useDocusaurusContext();
   const {pluginId} = useActivePlugin({
     failfast: true,
   });
-  const {savePreferredVersionName} = useDocsPreferredVersion(pluginId);
-  const activeVersion = useActiveVersion(pluginId);
-  const {
-    latestDocSuggestion,
-    latestVersionSuggestion,
-  } = useDocVersionSuggestions(pluginId); // No suggestion to be made
 
-  if (!latestVersionSuggestion) {
-    return <></>;
-  } // try to link to same doc in latest version (not always possible)
+  const getVersionMainDoc = (version) =>
+    version.docs.find((doc) => doc.id === version.mainDocId);
+
+  const {savePreferredVersionName} = useDocsPreferredVersion(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
 
   const latestVersionSuggestedDoc =
     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>
-        {activeVersion.name === 'current' ? (
-          <UnreleasedVersionLabel
-            siteTitle={siteTitle}
-            versionLabel={activeVersion.label}
-          />
-        ) : (
-          <UnmaintainedVersionLabel
-            siteTitle={siteTitle}
-            versionLabel={activeVersion.label}
-          />
-        )}
+        <BannerLabel siteTitle={siteTitle} versionMetadata={versionMetadata} />
       </div>
       <div className="margin-top--md">
         <LatestVersionSuggestionLabel
@@ -123,4 +128,17 @@ function DocVersionSuggestions() {
   );
 }
 
-export default DocVersionSuggestions;
+export default function DocVersionBanner({className}) {
+  const versionMetadata = useDocsVersion();
+
+  if (versionMetadata.banner) {
+    return (
+      <DocVersionBannerEnabled
+        className={className}
+        versionMetadata={versionMetadata}
+      />
+    );
+  }
+
+  return null;
+}

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

@@ -7,9 +7,14 @@
 import React from 'react';
 import Translate from '@docusaurus/Translate';
 import IconEdit from '@theme/IconEdit';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 export default function EditThisPage({editUrl}) {
   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/lib-next/theme/ErrorPageContent.js

@@ -0,0 +1,35 @@
+/**
+ * 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';
+export default function ErrorPageContent({error, tryAgain}) {
+  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>
+  );
+}