@docusaurus/theme-classic 2.0.0-beta.8bda3b2db → 2.0.0-beta.9

package/src/theme/DocSidebarItem/index.tsx

@@ -0,0 +1,206 @@
+/**
+ * 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, memo} from 'react';
+import clsx from 'clsx';
+import {
+  isSamePath,
+  usePrevious,
+  Collapsible,
+  useCollapsible,
+  ThemeClassNames,
+} from '@docusaurus/theme-common';
+import Link from '@docusaurus/Link';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import IconExternalLink from '@theme/IconExternalLink';
+
+import type {Props, DocSidebarItemsProps} from '@theme/DocSidebarItem';
+import type {
+  PropSidebarItemCategory,
+  PropSidebarItemLink,
+} from '@docusaurus/plugin-content-docs-types';
+
+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;
+};
+
+// 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 (
+    <>
+      {items.map((item, index) => (
+        <DocSidebarItem
+          key={index} // sidebar is static, the index does not change
+          item={item}
+          {...props}
+        />
+      ))}
+    </>
+  );
+});
+
+export default function DocSidebarItem({
+  item,
+  ...props
+}: Props): JSX.Element | null {
+  switch (item.type) {
+    case 'category':
+      if (item.items.length === 0) {
+        return null;
+      }
+      return <DocSidebarItemCategory 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,
+}: {
+  isActive: boolean;
+  collapsed: boolean;
+  setCollapsed: (b: boolean) => void;
+}) {
+  const wasActive = usePrevious(isActive);
+  useEffect(() => {
+    const justBecameActive = isActive && !wasActive;
+    if (justBecameActive && collapsed) {
+      setCollapsed(false);
+    }
+  }, [isActive, wasActive, collapsed, setCollapsed]);
+}
+
+function DocSidebarItemCategory({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  ...props
+}: Props & {item: PropSidebarItemCategory}) {
+  const {items, label, collapsible, className} = item;
+
+  const isActive = isActiveSidebarItem(item, activePath);
+
+  const {collapsed, setCollapsed, toggleCollapsed} = 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});
+
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemCategory,
+        ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
+        'menu__list-item',
+        {
+          'menu__list-item--collapsed': collapsed,
+        },
+        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>
+
+      <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 DocSidebarItemLink({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  ...props
+}: Props & {item: PropSidebarItemLink}) {
+  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,
+        })}
+        {...props}>
+        {isInternalUrl(href) ? (
+          label
+        ) : (
+          <span>
+            {label}
+            <IconExternalLink />
+          </span>
+        )}
+      </Link>
+    </li>
+  );
+}

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

@@ -0,0 +1,15 @@
+/**
+ * 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) {
+  .menuLinkText {
+    cursor: initial;
+  }
+  .menuLinkText:hover {
+    background: none;
+  }
+}

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-types';
+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}
+      searchMetadatas={{
+        // 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}
+      searchMetadatas={{
+        // 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/{DocVersionSuggestions → DocVersionBanner}/index.tsx

@@ -5,31 +5,40 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {ComponentType} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Link from '@docusaurus/Link';
 import Translate from '@docusaurus/Translate';
 import {
   useActivePlugin,
-  useActiveVersion,
   useDocVersionSuggestions,
+  GlobalVersion,
 } from '@theme/hooks/useDocs';
-import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+import {
+  ThemeClassNames,
+  useDocsPreferredVersion,
+} from '@docusaurus/theme-common';
+
+import type {Props} from '@theme/DocVersionBanner';
+import clsx from 'clsx';
+import type {VersionBanner} from '@docusaurus/plugin-content-docs-types';
+
+type BannerLabelComponentProps = {
+  siteTitle: string;
+  versionMetadata: Props['versionMetadata'];
+};
 
 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: <b>{versionLabel}</b>,
+        versionLabel: <b>{versionMetadata.label}</b>,
       }}>
       {
         'This is unreleased documentation for {siteTitle} {versionLabel} version.'
@@ -40,18 +49,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: <b>{versionLabel}</b>,
+        versionLabel: <b>{versionMetadata.label}</b>,
       }}>
       {
         'This is documentation for {siteTitle} {versionLabel}, which is no longer actively maintained.'
@@ -60,6 +66,20 @@ function UnmaintainedVersionLabel({
   );
 }
 
+const BannerLabelComponents: Record<
+  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,7 +92,7 @@ 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: (
@@ -94,27 +114,19 @@ function LatestVersionSuggestionLabel({
   );
 }
 
-const getVersionMainDoc = (version) =>
-  version.docs.find((doc) => doc.id === version.mainDocId);
-
-function DocVersionSuggestions(): JSX.Element {
+function DocVersionBannerEnabled({versionMetadata}: Props): 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
@@ -122,19 +134,14 @@ function DocVersionSuggestions(): JSX.Element {
     latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion);
 
   return (
-    <div className="alert alert--warning margin-bottom--md" role="alert">
+    <div
+      className={clsx(
+        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 +154,11 @@ function DocVersionSuggestions(): JSX.Element {
   );
 }
 
-export default DocVersionSuggestions;
+function DocVersionBanner({versionMetadata}: Props): JSX.Element {
+  if (versionMetadata.banner) {
+    return <DocVersionBannerEnabled versionMetadata={versionMetadata} />;
+  }
+  return <></>;
+}
+
+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/Footer/index.tsx

@@ -11,8 +11,10 @@ import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import {FooterLinkItem, useThemeConfig} from '@docusaurus/theme-common';
 import useBaseUrl from '@docusaurus/useBaseUrl';
+import isInternalUrl from '@docusaurus/isInternalUrl';
 import styles from './styles.module.css';
 import ThemedImage, {Props as ThemedImageProps} from '@theme/ThemedImage';
+import IconExternalLink from '@theme/IconExternalLink';
 
 function FooterLink({
   to,
@@ -35,7 +37,14 @@ function FooterLink({
             to: toUrl,
           })}
       {...props}>
-      {label}
+      {href && !isInternalUrl(href) ? (
+        <span>
+          {label}
+          <IconExternalLink />
+        </span>
+      ) : (
+        label
+      )}
     </Link>
   );
 }
@@ -43,8 +52,16 @@ function FooterLink({
 const FooterLogo = ({
   sources,
   alt,
-}: Pick<ThemedImageProps, 'sources' | 'alt'>) => (
-  <ThemedImage className="footer__logo" alt={alt} sources={sources} />
+  width,
+  height,
+}: Pick<ThemedImageProps, 'sources' | 'alt' | 'width' | 'height'>) => (
+  <ThemedImage
+    className="footer__logo"
+    alt={alt}
+    sources={sources}
+    width={width}
+    height={height}
+  />
 );
 
 function Footer(): JSX.Element | null {
@@ -106,7 +123,12 @@ function Footer(): JSX.Element | null {
               <div className="margin-bottom--sm">
                 {logo.href ? (
                   <Link href={logo.href} className={styles.footerLogoLink}>
-                    <FooterLogo alt={logo.alt} sources={sources} />
+                    <FooterLogo
+                      alt={logo.alt}
+                      sources={sources}
+                      width={logo.width}
+                      height={logo.height}
+                    />
                   </Link>
                 ) : (
                   <FooterLogo alt={logo.alt} sources={sources} />

package/src/theme/Heading/index.tsx

@@ -5,8 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable jsx-a11y/anchor-has-content, jsx-a11y/anchor-is-valid */
-
 import React from 'react';
 import clsx from 'clsx';
 import type {HeadingType, Props} from '@theme/Heading';
@@ -24,7 +22,7 @@ export const MainHeading: HeadingComponent = function MainHeading({...props}) {
       <h1
         {...props}
         id={undefined} // h1 headings do not need an id because they don't appear in the TOC
-        className={styles.h1Heading}>
+      >
         {props.children}
       </h1>
     </header>
@@ -44,17 +42,16 @@ const createAnchorHeading = (
     }
 
     return (
-      <Tag {...props}>
-        <a
-          aria-hidden="true"
-          tabIndex={-1}
-          className={clsx('anchor', {
-            [styles.enhancedAnchor]: !hideOnScroll,
-          })}
-          id={id}
-        />
+      <Tag
+        {...props}
+        className={clsx('anchor', {
+          [styles.anchorWithHideOnScrollNavbar]: hideOnScroll,
+          [styles.anchorWithStickyNavbar]: !hideOnScroll,
+        })}
+        id={id}>
         {props.children}
         <a
+          aria-hidden="true"
           className="hash-link"
           href={`#${id}`}
           title={translate({
@@ -62,7 +59,7 @@ const createAnchorHeading = (
             message: 'Direct link to heading',
             description: 'Title for link to heading',
           })}>
-          #
+          &#8203;
         </a>
       </Tag>
     );

package/src/theme/Heading/styles.css

@@ -5,18 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.anchor {
-  display: block;
-  position: relative;
-  top: -0.5rem;
-}
-
 .hash-link {
   opacity: 0;
   padding-left: 0.5rem;
   transition: opacity var(--ifm-transition-fast);
 }
 
+.hash-link:before {
+  content: '#';
+}
+
 .hash-link:focus,
 *:hover > .hash-link {
   opacity: 1;