@docusaurus/theme-classic 0.0.0-4238 → 0.0.0-4243

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "0.0.0-4238",
+  "version": "0.0.0-4243",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -23,21 +23,21 @@
     "update-code-translations": "node -e 'require(\"./update-code-translations.js\").run()'"
   },
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4238",
-    "@docusaurus/plugin-content-blog": "0.0.0-4238",
-    "@docusaurus/plugin-content-docs": "0.0.0-4238",
-    "@docusaurus/plugin-content-pages": "0.0.0-4238",
-    "@docusaurus/theme-common": "0.0.0-4238",
-    "@docusaurus/theme-translations": "0.0.0-4238",
-    "@docusaurus/utils": "0.0.0-4238",
-    "@docusaurus/utils-validation": "0.0.0-4238",
+    "@docusaurus/core": "0.0.0-4243",
+    "@docusaurus/plugin-content-blog": "0.0.0-4243",
+    "@docusaurus/plugin-content-docs": "0.0.0-4243",
+    "@docusaurus/plugin-content-pages": "0.0.0-4243",
+    "@docusaurus/theme-common": "0.0.0-4243",
+    "@docusaurus/theme-translations": "0.0.0-4243",
+    "@docusaurus/utils": "0.0.0-4243",
+    "@docusaurus/utils-validation": "0.0.0-4243",
     "@mdx-js/mdx": "^1.6.21",
     "@mdx-js/react": "^1.6.21",
     "chalk": "^4.1.2",
     "clsx": "^1.1.1",
     "copy-text-to-clipboard": "^3.0.1",
     "globby": "^11.0.2",
-    "infima": "0.2.0-alpha.34",
+    "infima": "0.2.0-alpha.36",
     "lodash": "^4.17.20",
     "postcss": "^8.3.7",
     "prism-react-renderer": "^1.2.1",
@@ -46,8 +46,8 @@
     "rtlcss": "^3.3.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4238",
-    "@docusaurus/types": "0.0.0-4238",
+    "@docusaurus/module-type-aliases": "0.0.0-4243",
+    "@docusaurus/types": "0.0.0-4243",
     "@types/mdx-js__react": "^1.5.4",
     "@types/parse-numeric-range": "^0.0.1",
     "@types/rtlcss": "^3.1.1",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "b461d8c0ec2fcea4f614bf5eec4ca700284bb42e"
+  "gitHead": "9ff41c223c3422e3483bc1049ee9ec703d11e0cd"
 }

package/src/index.ts

@@ -5,12 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {DocusaurusContext, Plugin} from '@docusaurus/types';
+import {DocusaurusContext, Plugin, PostCssOptions} from '@docusaurus/types';
 import type {ThemeConfig} from '@docusaurus/theme-common';
 import {getTranslationFiles, translateThemeConfig} from './translations';
 import path from 'path';
 import {createRequire} from 'module';
-import type {AcceptedPlugin, Plugin as PostCssPlugin} from 'postcss';
+import type {Plugin as PostCssPlugin} from 'postcss';
 import rtlcss from 'rtlcss';
 import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
 
@@ -132,7 +132,12 @@ export default function docusaurusThemeClassic(
     },
 
     getTranslationFiles: async () => getTranslationFiles({themeConfig}),
-    translateThemeConfig,
+
+    translateThemeConfig: (params) =>
+      translateThemeConfig({
+        themeConfig: params.themeConfig as ThemeConfig,
+        translationFiles: params.translationFiles,
+      }),
 
     getDefaultCodeTranslationMessages() {
       return readDefaultCodeTranslationMessages({
@@ -178,7 +183,7 @@ export default function docusaurusThemeClassic(
       };
     },
 
-    configurePostCss(postCssOptions: {plugins: AcceptedPlugin[]}) {
+    configurePostCss(postCssOptions: PostCssOptions) {
       if (direction === 'rtl') {
         const resolvedInfimaFile = require.resolve(getInfimaCSSFile(direction));
         const plugin: PostCssPlugin = {

package/src/theme/DocCard/index.tsx

@@ -0,0 +1,100 @@
+/**
+ * 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, {ReactNode} from 'react';
+import Link from '@docusaurus/Link';
+import {
+  PropSidebarItemCategory,
+  PropSidebarItemLink,
+} from '@docusaurus/plugin-content-docs';
+import type {Props} from '@theme/DocCard';
+import {findFirstCategoryLink, useDocById} from '@docusaurus/theme-common';
+import clsx from 'clsx';
+import styles from './styles.module.css';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+
+function CardContainer({
+  href,
+  children,
+}: {
+  href?: string;
+  children: ReactNode;
+}): JSX.Element {
+  const className = clsx(
+    'card margin-bottom--lg padding--lg',
+    styles.cardContainer,
+    href && styles.cardContainerLink,
+  );
+  return href ? (
+    <Link href={href} className={className}>
+      {children}
+    </Link>
+  ) : (
+    <div className={className}>{children}</div>
+  );
+}
+
+function CardLayout({
+  href,
+  icon,
+  title,
+  description,
+}: {
+  href?: string;
+  icon: ReactNode;
+  title: string;
+  description?: string;
+}): JSX.Element {
+  return (
+    <CardContainer href={href}>
+      <h2 className={clsx('text--truncate', styles.cardTitle)} title={title}>
+        {icon} {title}
+      </h2>
+      <div
+        className={clsx('text--truncate', styles.cardDescription)}
+        title={description}>
+        {description}
+      </div>
+    </CardContainer>
+  );
+}
+
+function CardCategory({item}: {item: PropSidebarItemCategory}): JSX.Element {
+  const href = findFirstCategoryLink(item);
+  return (
+    <CardLayout
+      href={href}
+      icon="🗃️"
+      title={item.label}
+      description={`${item.items.length} items`}
+    />
+  );
+}
+
+function CardLink({item}: {item: PropSidebarItemLink}): JSX.Element {
+  const icon = isInternalUrl(item.href) ? '📄️' : '🔗';
+  const doc = useDocById(item.docId ?? undefined);
+  return (
+    <CardLayout
+      href={item.href}
+      icon={icon}
+      title={item.label}
+      description={doc?.description}
+    />
+  );
+}
+
+export default function DocCard({item}: Props): JSX.Element {
+  switch (item.type) {
+    case 'link':
+      return <CardLink item={item} />;
+    case 'category':
+      return <CardCategory item={item} />;
+    default:
+      throw new Error(`unknown item type ${JSON.stringify(item)}`);
+  }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+
+.cardContainer {
+  height: 8rem;
+
+  color: var(--ifm-color-emphasis-800);
+  --ifm-link-color: var(--ifm-color-emphasis-800);
+  --ifm-link-hover-color: var(--ifm-color-emphasis-800);
+  --ifm-link-hover-decoration: none;
+
+  /* box-shadow: var(--ifm-global-shadow-lw); */
+  box-shadow: 0 1.5px 3px 0 rgba(0, 0, 0, 0.15);
+  border: 1px solid var(--ifm-color-emphasis-200);
+  transition: box-shadow var(--ifm-transition-fast) ease,
+    background-color var(--ifm-transition-fast) ease;
+}
+
+.cardContainer.cardContainerLink:hover {
+  /* box-shadow: var(--ifm-global-shadow-md); */
+  box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2);
+}
+html[data-theme='dark'] .cardContainer.cardContainerLink:hover {
+  --ifm-card-background-color: #2d2d2d; /* original, non-hovered color is #242526 */
+}
+
+.cardContainer:not(.cardContainerLink) {
+  cursor: not-allowed;
+}
+
+.cardTitle {
+  font-size: 1.2rem;
+  min-height: 1.2rem;
+}
+
+.cardDescription {
+  font-size: 0.8rem;
+  min-height: 0.8rem;
+}

package/src/theme/DocCardList/index.tsx

@@ -0,0 +1,27 @@
+/**
+ * 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 DocCard from '@theme/DocCard';
+import {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+export default function DocCardList({
+  items,
+}: {
+  items: PropSidebarItem[];
+}): JSX.Element {
+  return (
+    <div className="row">
+      {items.map((item, index) => (
+        <article key={index} className="col col--6">
+          <DocCard item={item} />
+        </article>
+      ))}
+    </div>
+  );
+}

package/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -0,0 +1,53 @@
+/**
+ * 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 {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+import type {Props} from '@theme/DocCategoryGeneratedIndexPage';
+import DocCardList from '@theme/DocCardList';
+import DocPaginator from '@theme/DocPaginator';
+import Seo from '@theme/Seo';
+import DocVersionBanner from '@theme/DocVersionBanner';
+import DocVersionBadge from '@theme/DocVersionBadge';
+import {MainHeading} from '@theme/Heading';
+
+import styles from './styles.module.css';
+
+export default function DocCategoryGeneratedIndexPage({
+  categoryGeneratedIndex,
+}: Props): JSX.Element {
+  const category = useCurrentSidebarCategory();
+  return (
+    <>
+      <Seo
+        title={categoryGeneratedIndex.title}
+        description={categoryGeneratedIndex.description}
+      />
+      <div className={styles.generatedIndexPage}>
+        <DocVersionBanner />
+        <DocVersionBadge />
+        <header>
+          <MainHeading className={styles.title}>
+            {categoryGeneratedIndex.title}
+          </MainHeading>
+          {categoryGeneratedIndex.description && (
+            <p>{categoryGeneratedIndex.description}</p>
+          )}
+        </header>
+        <main className="margin-top--lg">
+          <DocCardList items={category.items} />
+        </main>
+        <footer className="margin-top--lg">
+          <DocPaginator
+            previous={categoryGeneratedIndex.navigation.previous}
+            next={categoryGeneratedIndex.navigation.next}
+          />
+        </footer>
+      </div>
+    </>
+  );
+}

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

@@ -0,0 +1,18 @@
+/**
+ * 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) {
+  .generatedIndexPage {
+    max-width: 75% !important;
+  }
+}
+
+/* Duplicated from .markdown h1 */
+.title {
+  --ifm-h1-font-size: 3rem;
+  margin-bottom: calc(1.25 * var(--ifm-leading));
+}

package/src/theme/DocItem/index.tsx

@@ -10,6 +10,7 @@ import clsx from 'clsx';
 import useWindowSize from '@theme/hooks/useWindowSize';
 import DocPaginator from '@theme/DocPaginator';
 import DocVersionBanner from '@theme/DocVersionBanner';
+import DocVersionBadge from '@theme/DocVersionBadge';
 import Seo from '@theme/Seo';
 import type {Props} from '@theme/DocItem';
 import DocItemFooter from '@theme/DocItemFooter';
@@ -20,7 +21,7 @@ import styles from './styles.module.css';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 
 export default function DocItem(props: Props): JSX.Element {
-  const {content: DocContent, versionMetadata} = props;
+  const {content: DocContent} = props;
   const {metadata, frontMatter} = DocContent;
   const {
     image,
@@ -55,18 +56,10 @@ export default function DocItem(props: Props): JSX.Element {
           className={clsx('col', {
             [styles.docItemCol]: !hideTableOfContents,
           })}>
-          <DocVersionBanner versionMetadata={versionMetadata} />
+          <DocVersionBanner />
           <div className={styles.docItemContainer}>
             <article>
-              {versionMetadata.badge && (
-                <span
-                  className={clsx(
-                    ThemeClassNames.docs.docVersionBadge,
-                    'badge badge--secondary',
-                  )}>
-                  Version: {versionMetadata.label}
-                </span>
-              )}
+              <DocVersionBadge />
 
               {canRenderTOC && (
                 <TOCCollapsible
@@ -95,7 +88,7 @@ export default function DocItem(props: Props): JSX.Element {
               <DocItemFooter {...props} />
             </article>
 
-            <DocPaginator metadata={metadata} />
+            <DocPaginator previous={metadata.previous} next={metadata.next} />
           </div>
         </div>
         {renderTocDesktop && (

package/src/theme/DocPage/index.tsx

@@ -23,27 +23,30 @@ import {translate} from '@docusaurus/Translate';
 
 import clsx from 'clsx';
 import styles from './styles.module.css';
-import {ThemeClassNames, docVersionSearchTag} from '@docusaurus/theme-common';
+import {
+  ThemeClassNames,
+  docVersionSearchTag,
+  DocsSidebarProvider,
+  useDocsSidebar,
+  DocsVersionProvider,
+} from '@docusaurus/theme-common';
 import Head from '@docusaurus/Head';
 
 type DocPageContentProps = {
   readonly currentDocRoute: DocumentRoute;
   readonly versionMetadata: PropVersionMetadata;
   readonly children: ReactNode;
+  readonly sidebarName: string | undefined;
 };
 
 function DocPageContent({
   currentDocRoute,
   versionMetadata,
   children,
+  sidebarName,
 }: DocPageContentProps): JSX.Element {
+  const sidebar = useDocsSidebar();
   const {pluginId, version} = versionMetadata;
-
-  const sidebarName = currentDocRoute.sidebar;
-  const sidebar = sidebarName
-    ? versionMetadata.docsSidebars[sidebarName]
-    : undefined;
-
   const [hiddenSidebarContainer, setHiddenSidebarContainer] = useState(false);
   const [hiddenSidebar, setHiddenSidebar] = useState(false);
   const toggleSidebar = useCallback(() => {
@@ -150,17 +153,30 @@ function DocPage(props: Props): JSX.Element {
   if (!currentDocRoute) {
     return <NotFound />;
   }
+
+  // For now, the sidebarName is added as route config: not ideal!
+  const sidebarName = currentDocRoute.sidebar;
+
+  const sidebar = sidebarName
+    ? versionMetadata.docsSidebars[sidebarName]
+    : null;
+
   return (
     <>
       <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>
+      <DocsVersionProvider version={versionMetadata}>
+        <DocsSidebarProvider sidebar={sidebar}>
+          <DocPageContent
+            currentDocRoute={currentDocRoute}
+            versionMetadata={versionMetadata}
+            sidebarName={sidebarName}>
+            {renderRoutes(docRoutes, {versionMetadata})}
+          </DocPageContent>
+        </DocsSidebarProvider>
+      </DocsVersionProvider>
     </>
   );
 }

package/src/theme/DocPaginator/index.tsx

@@ -8,10 +8,10 @@
 import React from 'react';
 import Link from '@docusaurus/Link';
 import Translate, {translate} from '@docusaurus/Translate';
-import type {Props} from '@theme/DocPaginator';
+import type {PropNavigation} from '@docusaurus/plugin-content-docs';
 
-function DocPaginator(props: Props): JSX.Element {
-  const {metadata} = props;
+function DocPaginator(props: PropNavigation): JSX.Element {
+  const {previous, next} = props;
 
   return (
     <nav
@@ -22,10 +22,8 @@ function DocPaginator(props: Props): JSX.Element {
         description: 'The ARIA label for the docs pagination',
       })}>
       <div className="pagination-nav__item">
-        {metadata.previous && (
-          <Link
-            className="pagination-nav__link"
-            to={metadata.previous.permalink}>
+        {previous && (
+          <Link className="pagination-nav__link" to={previous.permalink}>
             <div className="pagination-nav__sublabel">
               <Translate
                 id="theme.docs.paginator.previous"
@@ -34,14 +32,14 @@ function DocPaginator(props: Props): JSX.Element {
               </Translate>
             </div>
             <div className="pagination-nav__label">
-              &laquo; {metadata.previous.title}
+              &laquo; {previous.title}
             </div>
           </Link>
         )}
       </div>
       <div className="pagination-nav__item pagination-nav__item--next">
-        {metadata.next && (
-          <Link className="pagination-nav__link" to={metadata.next.permalink}>
+        {next && (
+          <Link className="pagination-nav__link" to={next.permalink}>
             <div className="pagination-nav__sublabel">
               <Translate
                 id="theme.docs.paginator.next"
@@ -49,9 +47,7 @@ function DocPaginator(props: Props): JSX.Element {
                 Next
               </Translate>
             </div>
-            <div className="pagination-nav__label">
-              {metadata.next.title} &raquo;
-            </div>
+            <div className="pagination-nav__label">{next.title} &raquo;</div>
           </Link>
         )}
       </div>

package/src/theme/DocSidebar/index.tsx

@@ -100,7 +100,15 @@ const DocSidebarMobileSecondaryMenu: MobileSecondaryMenuComponent<Props> = ({
     <DocSidebarItems
       items={sidebar}
       activePath={path}
-      onItemClick={() => toggleSidebar()}
+      onItemClick={(item) => {
+        // Mobile sidebar should only be closed if the category has a link
+        if (item.type === 'category' && item.href) {
+          toggleSidebar();
+        }
+        if (item.type === 'link') {
+          toggleSidebar();
+        }
+      }}
       level={1}
     />
   </ul>