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

package/src/theme/DocPage/index.tsx

@@ -8,7 +8,6 @@
 import React, {ReactNode, useState, useCallback} from 'react';
 import {MDXProvider} from '@mdx-js/react';
 
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import renderRoutes from '@docusaurus/renderRoutes';
 import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types';
 import Layout from '@theme/Layout';
@@ -25,6 +24,7 @@ import {translate} from '@docusaurus/Translate';
 import clsx from 'clsx';
 import styles from './styles.module.css';
 import {ThemeClassNames, docVersionSearchTag} from '@docusaurus/theme-common';
+import Head from '@docusaurus/Head';
 
 type DocPageContentProps = {
   readonly currentDocRoute: DocumentRoute;
@@ -37,7 +37,6 @@ function DocPageContent({
   versionMetadata,
   children,
 }: DocPageContentProps): JSX.Element {
-  const {isClient} = useDocusaurusContext();
   const {pluginId, version} = versionMetadata;
 
   const sidebarName = currentDocRoute.sidebar;
@@ -52,14 +51,13 @@ function DocPageContent({
       setHiddenSidebar(false);
     }
 
-    setHiddenSidebarContainer(!hiddenSidebarContainer);
+    setHiddenSidebarContainer((value) => !value);
   }, [hiddenSidebar]);
 
   return (
     <Layout
-      key={isClient}
-      wrapperClassName={ThemeClassNames.wrapper.docPages}
-      pageClassName={ThemeClassNames.page.docPage}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
+      pageClassName={ThemeClassNames.page.docsDocPage}
       searchMetadatas={{
         version,
         tag: docVersionSearchTag(pluginId, version),
@@ -150,14 +148,20 @@ function DocPage(props: Props): JSX.Element {
     matchPath(location.pathname, docRoute),
   );
   if (!currentDocRoute) {
-    return <NotFound {...props} />;
+    return <NotFound />;
   }
   return (
-    <DocPageContent
-      currentDocRoute={currentDocRoute}
-      versionMetadata={versionMetadata}>
-      {renderRoutes(docRoutes, {versionMetadata})}
-    </DocPageContent>
+    <>
+      <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>
+    </>
   );
 }
 

package/src/theme/DocSidebar/index.tsx

@@ -12,9 +12,10 @@ import {
   useAnnouncementBar,
   MobileSecondaryMenuFiller,
   MobileSecondaryMenuComponent,
+  ThemeClassNames,
+  useScrollPosition,
 } from '@docusaurus/theme-common';
 import useWindowSize from '@theme/hooks/useWindowSize';
-import useScrollPosition from '@theme/hooks/useScrollPosition';
 import Logo from '@theme/Logo';
 import IconArrow from '@theme/IconArrow';
 import {translate} from '@docusaurus/Translate';
@@ -24,17 +25,21 @@ import type {Props} from '@theme/DocSidebar';
 import styles from './styles.module.css';
 
 function useShowAnnouncementBar() {
-  const {isClosed} = useAnnouncementBar();
-  const [showAnnouncementBar, setShowAnnouncementBar] = useState(!isClosed);
-  useScrollPosition(({scrollY}) => {
-    if (!isClosed) {
-      setShowAnnouncementBar(scrollY === 0);
-    }
-  });
-  return showAnnouncementBar;
+  const {isActive} = useAnnouncementBar();
+  const [showAnnouncementBar, setShowAnnouncementBar] = useState(isActive);
+
+  useScrollPosition(
+    ({scrollY}) => {
+      if (isActive) {
+        setShowAnnouncementBar(scrollY === 0);
+      }
+    },
+    [isActive],
+  );
+  return isActive && showAnnouncementBar;
 }
 
-function HideableSidebarButton({onClick}) {
+function HideableSidebarButton({onClick}: {onClick: React.MouseEventHandler}) {
   return (
     <button
       type="button"
@@ -64,7 +69,6 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
     navbar: {hideOnScroll},
     hideableSidebar,
   } = useThemeConfig();
-  const {isClosed: isAnnouncementBarClosed} = useAnnouncementBar();
 
   return (
     <div
@@ -75,11 +79,10 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
       {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
       <nav
         className={clsx('menu thin-scrollbar', styles.menu, {
-          [styles.menuWithAnnouncementBar]:
-            !isAnnouncementBarClosed && showAnnouncementBar,
+          [styles.menuWithAnnouncementBar]: showAnnouncementBar,
         })}>
-        <ul className="menu__list">
-          <DocSidebarItems items={sidebar} activePath={path} />
+        <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
+          <DocSidebarItems items={sidebar} activePath={path} level={1} />
         </ul>
       </nav>
       {hideableSidebar && <HideableSidebarButton onClick={onCollapse} />}
@@ -93,11 +96,12 @@ const DocSidebarMobileSecondaryMenu: MobileSecondaryMenuComponent<Props> = ({
   path,
 }) => {
   return (
-    <ul className="menu__list">
+    <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
       <DocSidebarItems
         items={sidebar}
         activePath={path}
         onItemClick={() => toggleSidebar()}
+        level={1}
       />
     </ul>
   );

package/src/theme/DocSidebarItem/index.tsx

@@ -12,6 +12,7 @@ import {
   usePrevious,
   Collapsible,
   useCollapsible,
+  ThemeClassNames,
 } from '@docusaurus/theme-common';
 import Link from '@docusaurus/Link';
 import isInternalUrl from '@docusaurus/isInternalUrl';
@@ -25,7 +26,10 @@ import type {
 
 import styles from './styles.module.css';
 
-const isActiveSidebarItem = (item: Props['item'], activePath: string) => {
+const isActiveSidebarItem = (
+  item: Props['item'],
+  activePath: string,
+): boolean => {
   if (item.type === 'link') {
     return isSamePath(item.href, activePath);
   }
@@ -89,16 +93,17 @@ function useAutoExpandActiveCategory({
     if (justBecameActive && collapsed) {
       setCollapsed(false);
     }
-  }, [isActive, wasActive, collapsed]);
+  }, [isActive, wasActive, collapsed, setCollapsed]);
 }
 
 function DocSidebarItemCategory({
   item,
   onItemClick,
   activePath,
+  level,
   ...props
 }: Props & {item: PropSidebarItemCategory}) {
-  const {items, label, collapsible} = item;
+  const {items, label, collapsible, className} = item;
 
   const isActive = isActiveSidebarItem(item, activePath);
 
@@ -117,9 +122,15 @@ function DocSidebarItemCategory({
 
   return (
     <li
-      className={clsx('menu__list-item', {
-        'menu__list-item--collapsed': collapsed,
-      })}>
+      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', {
@@ -146,6 +157,7 @@ function DocSidebarItemCategory({
           tabIndex={collapsed ? -1 : 0}
           onItemClick={onItemClick}
           activePath={activePath}
+          level={level + 1}
         />
       </Collapsible>
     </li>
@@ -156,20 +168,27 @@ function DocSidebarItemLink({
   item,
   onItemClick,
   activePath,
+  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,
         })}
         {...props}>

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/DocVersionBanner/index.tsx

@@ -9,10 +9,19 @@ 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,
+} 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;
@@ -58,7 +67,7 @@ function UnmaintainedVersionLabel({
 }
 
 const BannerLabelComponents: Record<
-  Exclude<Props['versionMetadata']['banner'], 'none'>,
+  VersionBanner,
   ComponentType<BannerLabelComponentProps>
 > = {
   unreleased: UnreleasedVersionLabel,
@@ -67,7 +76,7 @@ const BannerLabelComponents: Record<
 
 function BannerLabel(props: BannerLabelComponentProps) {
   const BannerLabelComponent =
-    BannerLabelComponents[props.versionMetadata.banner];
+    BannerLabelComponents[props.versionMetadata.banner!];
   return <BannerLabelComponent {...props} />;
 }
 
@@ -109,17 +118,15 @@ function DocVersionBannerEnabled({versionMetadata}: Props): 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 +134,12 @@ function DocVersionBannerEnabled({versionMetadata}: Props): 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>
         <BannerLabel siteTitle={siteTitle} versionMetadata={versionMetadata} />
       </div>
@@ -143,11 +155,10 @@ function DocVersionBannerEnabled({versionMetadata}: Props): JSX.Element {
 }
 
 function DocVersionBanner({versionMetadata}: Props): JSX.Element {
-  if (versionMetadata.banner === 'none') {
-    return <></>;
-  } else {
+  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

@@ -52,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 {
@@ -115,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;

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

@@ -5,11 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.enhancedAnchor {
-  top: calc(var(--ifm-navbar-height) * -1 - 0.5rem);
+/*
+When the navbar is sticky, ensure that on anchor click,
+the browser does not scroll that anchor behind the navbar
+See https://twitter.com/JoshWComeau/status/1332015868725891076
+ */
+.anchorWithStickyNavbar {
+  scroll-margin-top: calc(var(--ifm-navbar-height) + 0.5rem);
 }
 
-.h1Heading {
-  font-size: 3rem;
-  margin-bottom: calc(var(--ifm-leading-desktop) * var(--ifm-leading));
+.anchorWithHideOnScrollNavbar {
+  scroll-margin-top: 0.5rem;
 }

package/src/theme/IconClose/index.tsx

@@ -0,0 +1,26 @@
+/**
+ * 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/IconClose';
+
+export default function IconClose({
+  width = 21,
+  height = 21,
+  color = 'currentColor',
+  strokeWidth = 1.2,
+  className,
+  ...restProps
+}: Props): JSX.Element {
+  return (
+    <svg viewBox="0 0 15 15" width={width} height={height} {...restProps}>
+      <g stroke={color} strokeWidth={strokeWidth}>
+        <path d="M.75.75l13.5 13.5M14.25.75L.75 14.25" />
+      </g>
+    </svg>
+  );
+}

package/src/theme/LastUpdated/index.tsx

@@ -8,6 +8,7 @@
 import React from 'react';
 import Translate from '@docusaurus/Translate';
 import type {Props} from '@theme/LastUpdated';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 function LastUpdatedAtDate({
   lastUpdatedAt,
@@ -57,7 +58,7 @@ export default function LastUpdated({
   lastUpdatedBy,
 }: Props): JSX.Element {
   return (
-    <>
+    <span className={ThemeClassNames.common.lastUpdated}>
       <Translate
         id="theme.lastUpdated.lastUpdatedAtBy"
         description="The sentence used to display when a page has been last updated, and by who"
@@ -84,6 +85,6 @@ export default function LastUpdated({
           <small> (Simulated during dev for better perf)</small>
         </div>
       )}
-    </>
+    </span>
   );
 }