@docusaurus/theme-classic 2.0.0-beta.1decd6f80 → 2.0.0-beta.20

package/src/theme/{DocVersionSuggestions → DocVersionBanner}/index.tsx

@@ -5,31 +5,44 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {type ComponentType} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Link from '@docusaurus/Link';
 import Translate from '@docusaurus/Translate';
 import {
   useActivePlugin,
-  useActiveVersion,
   useDocVersionSuggestions,
-} from '@theme/hooks/useDocs';
-import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+  type GlobalVersion,
+} from '@docusaurus/plugin-content-docs/client';
+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: PropVersionMetadata;
+};
 
 function UnreleasedVersionLabel({
   siteTitle,
-  versionLabel,
-}: {
-  siteTitle: string;
-  versionLabel: string;
-}) {
+  versionMetadata,
+}: BannerLabelComponentProps) {
   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.'
@@ -40,18 +53,15 @@ function UnreleasedVersionLabel({
 
 function UnmaintainedVersionLabel({
   siteTitle,
-  versionLabel,
-}: {
-  siteTitle: string;
-  versionLabel: string;
-}) {
+  versionMetadata,
+}: BannerLabelComponentProps) {
   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.'
@@ -60,6 +70,19 @@ function UnmaintainedVersionLabel({
   );
 }
 
+const BannerLabelComponents: {
+  [banner in VersionBanner]: ComponentType<BannerLabelComponentProps>;
+} = {
+  unreleased: UnreleasedVersionLabel,
+  unmaintained: UnmaintainedVersionLabel,
+};
+
+function BannerLabel(props: BannerLabelComponentProps) {
+  const BannerLabelComponent =
+    BannerLabelComponents[props.versionMetadata.banner!];
+  return <BannerLabelComponent {...props} />;
+}
+
 function LatestVersionSuggestionLabel({
   versionLabel,
   to,
@@ -72,11 +95,11 @@ function LatestVersionSuggestionLabel({
   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"
@@ -84,7 +107,7 @@ function LatestVersionSuggestionLabel({
                 latest version
               </Translate>
             </Link>
-          </strong>
+          </b>
         ),
       }}>
       {
@@ -94,47 +117,40 @@ function LatestVersionSuggestionLabel({
   );
 }
 
-const getVersionMainDoc = (version) =>
-  version.docs.find((doc) => doc.id === version.mainDocId);
-
-function DocVersionSuggestions(): 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 {savePreferredVersionName} = useDocsPreferredVersion(pluginId);
+  const getVersionMainDoc = (version: GlobalVersion) =>
+    version.docs.find((doc) => doc.id === version.mainDocId)!;
 
-  const activeVersion = useActiveVersion(pluginId);
-  const {
-    latestDocSuggestion,
-    latestVersionSuggestion,
-  } = useDocVersionSuggestions(pluginId);
+  const {savePreferredVersionName} = useDocsPreferredVersion(pluginId);
 
-  // No suggestion to be made
-  if (!latestVersionSuggestion) {
-    return <></>;
-  }
+  const {latestDocSuggestion, latestVersionSuggestion} =
+    useDocVersionSuggestions(pluginId);
 
-  // try to link to same doc in latest version (not always possible)
-  // fallback to main doc of latest version
+  // Try to link to same doc in latest version (not always possible), falling
+  // back 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
@@ -147,4 +163,17 @@ function DocVersionSuggestions(): JSX.Element {
   );
 }
 
-export default DocVersionSuggestions;
+export default function DocVersionBanner({
+  className,
+}: Props): JSX.Element | null {
+  const versionMetadata = useDocsVersion();
+  if (versionMetadata.banner) {
+    return (
+      <DocVersionBannerEnabled
+        className={className}
+        versionMetadata={versionMetadata}
+      />
+    );
+  }
+  return null;
+}

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

package/src/theme/Footer/Copyright/index.tsx

@@ -0,0 +1,20 @@
+/**
+ * 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 type {Props} from '@theme/Footer/Copyright';
+
+export default function FooterCopyright({copyright}: Props): JSX.Element {
+  return (
+    <div
+      className="footer__copyright"
+      // Developer provided the HTML, so assume it's safe.
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{__html: copyright}}
+    />
+  );
+}

package/src/theme/Footer/Layout/index.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 type {Props} from '@theme/Footer/Layout';
+
+export default function FooterLayout({
+  style,
+  links,
+  logo,
+  copyright,
+}: Props): JSX.Element {
+  return (
+    <footer
+      className={clsx('footer', {
+        'footer--dark': style === 'dark',
+      })}>
+      <div className="container container-fluid">
+        {links}
+        {(logo || copyright) && (
+          <div className="footer__bottom text--center">
+            {logo && <div className="margin-bottom--sm">{logo}</div>}
+            {copyright}
+          </div>
+        )}
+      </div>
+    </footer>
+  );
+}

package/src/theme/Footer/LinkItem/index.tsx

@@ -0,0 +1,36 @@
+/**
+ * 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 useBaseUrl from '@docusaurus/useBaseUrl';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import IconExternalLink from '@theme/IconExternalLink';
+import type {Props} from '@theme/Footer/LinkItem';
+
+export default function FooterLinkItem({item}: Props): JSX.Element {
+  const {to, href, label, prependBaseUrlToHref, ...props} = item;
+  const toUrl = useBaseUrl(to);
+  const normalizedHref = useBaseUrl(href, {forcePrependBaseUrl: true});
+
+  return (
+    <Link
+      className="footer__link-item"
+      {...(href
+        ? {
+            href: prependBaseUrlToHref ? normalizedHref : href,
+          }
+        : {
+            to: toUrl,
+          })}
+      {...props}>
+      {label}
+      {href && !isInternalUrl(href) && <IconExternalLink />}
+    </Link>
+  );
+}

package/src/theme/Footer/Links/MultiColumn/index.tsx

@@ -0,0 +1,51 @@
+/**
+ * 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 type {Props} from '@theme/Footer/Links/MultiColumn';
+import LinkItem from '@theme/Footer/LinkItem';
+
+type ColumnType = Props['columns'][number];
+type ColumnItemType = ColumnType['items'][number];
+
+function ColumnLinkItem({item}: {item: ColumnItemType}) {
+  return item.html ? (
+    <li
+      className="footer__item"
+      // Developer provided the HTML, so assume it's safe.
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{__html: item.html}}
+    />
+  ) : (
+    <li key={item.href || item.to} className="footer__item">
+      <LinkItem item={item} />
+    </li>
+  );
+}
+
+function Column({column}: {column: ColumnType}) {
+  return (
+    <div className="col footer__col">
+      <div className="footer__title">{column.title}</div>
+      <ul className="footer__items clean-list">
+        {column.items.map((item, i) => (
+          <ColumnLinkItem key={i} item={item} />
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+export default function FooterLinksMultiColumn({columns}: Props): JSX.Element {
+  return (
+    <div className="row footer__links">
+      {columns.map((column, i) => (
+        <Column key={i} column={column} />
+      ))}
+    </div>
+  );
+}

package/src/theme/Footer/Links/Simple/index.tsx

@@ -0,0 +1,42 @@
+/**
+ * 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 type {Props} from '@theme/Footer/Links/Simple';
+import LinkItem from '@theme/Footer/LinkItem';
+
+function Separator() {
+  return <span className="footer__link-separator">·</span>;
+}
+
+function SimpleLinkItem({item}: {item: Props['links'][number]}) {
+  return item.html ? (
+    <span
+      className="footer__link-item"
+      // Developer provided the HTML, so assume it's safe.
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{__html: item.html}}
+    />
+  ) : (
+    <LinkItem item={item} />
+  );
+}
+
+export default function FooterLinksSimple({links}: Props): JSX.Element {
+  return (
+    <div className="footer__links text--center">
+      <div className="footer__links">
+        {links.map((item, i) => (
+          <React.Fragment key={i}>
+            <SimpleLinkItem item={item} />
+            {links.length !== i + 1 && <Separator />}
+          </React.Fragment>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/theme/Footer/Links/index.tsx

@@ -0,0 +1,21 @@
+/**
+ * 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 {isMultiColumnFooterLinks} from '@docusaurus/theme-common';
+import type {Props} from '@theme/Footer/Links';
+import FooterLinksMultiColumn from '@theme/Footer/Links/MultiColumn';
+import FooterLinksSimple from '@theme/Footer/Links/Simple';
+
+export default function FooterLinks({links}: Props): JSX.Element {
+  return isMultiColumnFooterLinks(links) ? (
+    <FooterLinksMultiColumn columns={links} />
+  ) : (
+    <FooterLinksSimple links={links} />
+  );
+}

package/src/theme/Footer/Logo/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 Link from '@docusaurus/Link';
+import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
+import styles from './styles.module.css';
+import ThemedImage from '@theme/ThemedImage';
+import type {Props} from '@theme/Footer/Logo';
+
+function LogoImage({logo}: Props) {
+  const {withBaseUrl} = useBaseUrlUtils();
+  const sources = {
+    light: withBaseUrl(logo.src),
+    dark: withBaseUrl(logo.srcDark ?? logo.src),
+  };
+  return (
+    <ThemedImage
+      className="footer__logo"
+      alt={logo.alt}
+      sources={sources}
+      width={logo.width}
+      height={logo.height}
+    />
+  );
+}
+
+export default function FooterLogo({logo}: Props): JSX.Element {
+  return logo.href ? (
+    <Link href={logo.href} className={styles.footerLogoLink}>
+      <LogoImage logo={logo} />
+    </Link>
+  ) : (
+    <LogoImage logo={logo} />
+  );
+}

package/{lib/theme/Footer → src/theme/Footer/Logo}/styles.module.css

@@ -7,7 +7,8 @@
 
 .footerLogoLink {
   opacity: 0.5;
-  transition: opacity var(--ifm-transition-fast) var(--ifm-transition-timing-default);
+  transition: opacity var(--ifm-transition-fast)
+    var(--ifm-transition-timing-default);
 }
 
 .footerLogoLink:hover {

package/src/theme/Footer/index.tsx

@@ -6,128 +6,28 @@
  */
 
 import React from 'react';
-import clsx from 'clsx';
 
-import Link from '@docusaurus/Link';
-import {FooterLinkItem, useThemeConfig} from '@docusaurus/theme-common';
-import useBaseUrl from '@docusaurus/useBaseUrl';
-import styles from './styles.module.css';
-import ThemedImage, {Props as ThemedImageProps} from '@theme/ThemedImage';
-
-function FooterLink({
-  to,
-  href,
-  label,
-  prependBaseUrlToHref,
-  ...props
-}: FooterLinkItem) {
-  const toUrl = useBaseUrl(to);
-  const normalizedHref = useBaseUrl(href, {forcePrependBaseUrl: true});
-
-  return (
-    <Link
-      className="footer__link-item"
-      {...(href
-        ? {
-            href: prependBaseUrlToHref ? normalizedHref : href,
-          }
-        : {
-            to: toUrl,
-          })}
-      {...props}>
-      {label}
-    </Link>
-  );
-}
-
-const FooterLogo = ({
-  sources,
-  alt,
-}: Pick<ThemedImageProps, 'sources' | 'alt'>) => (
-  <ThemedImage className="footer__logo" alt={alt} sources={sources} />
-);
+import {useThemeConfig} from '@docusaurus/theme-common';
+import FooterLinks from '@theme/Footer/Links';
+import FooterLogo from '@theme/Footer/Logo';
+import FooterCopyright from '@theme/Footer/Copyright';
+import FooterLayout from '@theme/Footer/Layout';
 
 function Footer(): JSX.Element | null {
   const {footer} = useThemeConfig();
-
-  const {copyright, links = [], logo = {}} = footer || {};
-  const sources = {
-    light: useBaseUrl(logo.src),
-    dark: useBaseUrl(logo.srcDark || logo.src),
-  };
-
   if (!footer) {
     return null;
   }
+  const {copyright, links, logo, style} = footer;
 
   return (
-    <footer
-      className={clsx('footer', {
-        'footer--dark': footer.style === 'dark',
-      })}>
-      <div className="container">
-        {links && links.length > 0 && (
-          <div className="row footer__links">
-            {links.map((linkItem, i) => (
-              <div key={i} className="col footer__col">
-                {linkItem.title != null ? (
-                  <div className="footer__title">{linkItem.title}</div>
-                ) : null}
-                {linkItem.items != null &&
-                Array.isArray(linkItem.items) &&
-                linkItem.items.length > 0 ? (
-                  <ul className="footer__items">
-                    {linkItem.items.map((item, key) =>
-                      item.html ? (
-                        <li
-                          key={key}
-                          className="footer__item"
-                          // Developer provided the HTML, so assume it's safe.
-                          // eslint-disable-next-line react/no-danger
-                          dangerouslySetInnerHTML={{
-                            __html: item.html,
-                          }}
-                        />
-                      ) : (
-                        <li key={item.href || item.to} className="footer__item">
-                          <FooterLink {...item} />
-                        </li>
-                      ),
-                    )}
-                  </ul>
-                ) : null}
-              </div>
-            ))}
-          </div>
-        )}
-        {(logo || copyright) && (
-          <div className="footer__bottom text--center">
-            {logo && (logo.src || logo.srcDark) && (
-              <div className="margin-bottom--sm">
-                {logo.href ? (
-                  <Link href={logo.href} className={styles.footerLogoLink}>
-                    <FooterLogo alt={logo.alt} sources={sources} />
-                  </Link>
-                ) : (
-                  <FooterLogo alt={logo.alt} sources={sources} />
-                )}
-              </div>
-            )}
-            {copyright ? (
-              <div
-                className="footer__copyright"
-                // Developer provided the HTML, so assume it's safe.
-                // eslint-disable-next-line react/no-danger
-                dangerouslySetInnerHTML={{
-                  __html: copyright,
-                }}
-              />
-            ) : null}
-          </div>
-        )}
-      </div>
-    </footer>
+    <FooterLayout
+      style={style}
+      links={links && links.length > 0 && <FooterLinks links={links} />}
+      logo={logo && <FooterLogo logo={logo} />}
+      copyright={copyright && <FooterCopyright copyright={copyright} />}
+    />
   );
 }
 
-export default Footer;
+export default React.memo(Footer);