@docusaurus/theme-classic 3.7.0 → 3.8.0-canary-6327

package/lib/theme/CodeBlock/Content/styles.module.css

@@ -5,33 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.codeBlockContent {
-  position: relative;
-  /* rtl:ignore */
-  direction: ltr;
-  border-radius: inherit;
-}
-
-.codeBlockTitle {
-  border-bottom: 1px solid var(--ifm-color-emphasis-300);
-  font-size: var(--ifm-code-font-size);
-  font-weight: 500;
-  padding: 0.75rem var(--ifm-pre-padding);
-  border-top-left-radius: inherit;
-  border-top-right-radius: inherit;
-}
-
 .codeBlock {
   --ifm-pre-background: var(--prism-background-color);
   margin: 0;
   padding: 0;
 }
 
-.codeBlockTitle + .codeBlockContent .codeBlock {
-  border-top-left-radius: 0;
-  border-top-right-radius: 0;
-}
-
 .codeBlockStandalone {
   padding: 0;
 }
@@ -54,34 +33,3 @@
     white-space: pre-wrap;
   }
 }
-
-.buttonGroup {
-  display: flex;
-  column-gap: 0.2rem;
-  position: absolute;
-  /* rtl:ignore */
-  right: calc(var(--ifm-pre-padding) / 2);
-  top: calc(var(--ifm-pre-padding) / 2);
-}
-
-.buttonGroup button {
-  display: flex;
-  align-items: center;
-  background: var(--prism-background-color);
-  color: var(--prism-color);
-  border: 1px solid var(--ifm-color-emphasis-300);
-  border-radius: var(--ifm-global-radius);
-  padding: 0.4rem;
-  line-height: 0;
-  transition: opacity var(--ifm-transition-fast) ease-in-out;
-  opacity: 0;
-}
-
-.buttonGroup button:focus-visible,
-.buttonGroup button:hover {
-  opacity: 1 !important;
-}
-
-:global(.theme-code-block:hover) .buttonGroup button {
-  opacity: 0.4;
-}

package/lib/theme/CodeBlock/Layout/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 { type ReactNode } from 'react';
+import type { Props } from '@theme/CodeBlock/Layout';
+export default function CodeBlockLayout({ className }: Props): ReactNode;

package/lib/theme/CodeBlock/Layout/index.js

@@ -0,0 +1,30 @@
+/**
+ * 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 {useCodeBlockContext} from '@docusaurus/theme-common/internal';
+import Container from '@theme/CodeBlock/Container';
+import Title from '@theme/CodeBlock/Title';
+import Content from '@theme/CodeBlock/Content';
+import Buttons from '@theme/CodeBlock/Buttons';
+import styles from './styles.module.css';
+export default function CodeBlockLayout({className}) {
+  const {metadata} = useCodeBlockContext();
+  return (
+    <Container as="div" className={clsx(className, metadata.className)}>
+      {metadata.title && (
+        <div className={styles.codeBlockTitle}>
+          <Title>{metadata.title}</Title>
+        </div>
+      )}
+      <div className={styles.codeBlockContent}>
+        <Content />
+        <Buttons />
+      </div>
+    </Container>
+  );
+}

package/lib/theme/CodeBlock/Layout/styles.module.css

@@ -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.
+ */
+
+.codeBlockContent {
+  position: relative;
+  /* rtl:ignore */
+  direction: ltr;
+  border-radius: inherit;
+}
+
+.codeBlockTitle {
+  border-bottom: 1px solid var(--ifm-color-emphasis-300);
+  font-size: var(--ifm-code-font-size);
+  font-weight: 500;
+  padding: 0.75rem var(--ifm-pre-padding);
+  border-top-left-radius: inherit;
+  border-top-right-radius: inherit;
+}
+
+.codeBlockTitle + .codeBlockContent .codeBlock {
+  border-top-left-radius: 0;
+  border-top-right-radius: 0;
+}

package/lib/theme/CodeBlock/Line/Token/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 { type ReactNode } from 'react';
+import type { Props } from '@theme/CodeBlock/Line/Token';
+export default function CodeBlockLineToken({ line, token, ...props }: Props): ReactNode;

package/lib/theme/CodeBlock/Line/Token/index.js

@@ -0,0 +1,11 @@
+/**
+ * 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';
+// Pass-through components that users can swizzle and customize
+export default function CodeBlockLineToken({line, token, ...props}) {
+  return <span {...props} />;
+}

package/lib/theme/CodeBlock/Line/index.d.ts

@@ -6,4 +6,4 @@
  */
 import { type ReactNode } from 'react';
 import type { Props } from '@theme/CodeBlock/Line';
-export default function CodeBlockLine({ line, classNames, showLineNumbers, getLineProps, getTokenProps, }: Props): ReactNode;
+export default function CodeBlockLine({ line: lineProp, classNames, showLineNumbers, getLineProps, getTokenProps, }: Props): ReactNode;

package/lib/theme/CodeBlock/Line/index.js

@@ -6,24 +6,38 @@
  */
 import React from 'react';
 import clsx from 'clsx';
+import LineToken from '@theme/CodeBlock/Line/Token';
 import styles from './styles.module.css';
+// Replaces '\n' by ''
+// Historical code, not sure why we even need this :/
+function fixLineBreak(line) {
+  const singleLineBreakToken =
+    line.length === 1 && line[0].content === '\n' ? line[0] : undefined;
+  if (singleLineBreakToken) {
+    return [{...singleLineBreakToken, content: ''}];
+  }
+  return line;
+}
 export default function CodeBlockLine({
-  line,
+  line: lineProp,
   classNames,
   showLineNumbers,
   getLineProps,
   getTokenProps,
 }) {
-  if (line.length === 1 && line[0].content === '\n') {
-    line[0].content = '';
-  }
+  const line = fixLineBreak(lineProp);
   const lineProps = getLineProps({
     line,
     className: clsx(classNames, showLineNumbers && styles.codeLine),
   });
-  const lineTokens = line.map((token, key) => (
-    <span key={key} {...getTokenProps({token})} />
-  ));
+  const lineTokens = line.map((token, key) => {
+    const tokenProps = getTokenProps({token});
+    return (
+      <LineToken key={key} {...tokenProps} line={line} token={token}>
+        {tokenProps.children}
+      </LineToken>
+    );
+  });
   return (
     <span {...lineProps}>
       {showLineNumbers ? (

package/lib/theme/CodeBlock/Title/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 type { ReactNode } from 'react';
+import type { Props } from '@theme/CodeBlock/Title';
+export default function CodeBlockTitle({ children }: Props): ReactNode;

package/lib/theme/CodeBlock/Title/index.js

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+// Just a pass-through component that users can swizzle and customize
+export default function CodeBlockTitle({children}) {
+  return children;
+}

package/lib/theme/ColorModeToggle/index.d.ts

@@ -6,6 +6,6 @@
  */
 import React, { type ReactNode } from 'react';
 import type { Props } from '@theme/ColorModeToggle';
-declare function ColorModeToggle({ className, buttonClassName, value, onChange, }: Props): ReactNode;
+declare function ColorModeToggle({ className, buttonClassName, respectPrefersColorScheme, value, onChange, }: Props): ReactNode;
 declare const _default: React.MemoExoticComponent<typeof ColorModeToggle>;
 export default _default;

package/lib/theme/ColorModeToggle/index.js

@@ -10,30 +10,93 @@ import useIsBrowser from '@docusaurus/useIsBrowser';
 import {translate} from '@docusaurus/Translate';
 import IconLightMode from '@theme/Icon/LightMode';
 import IconDarkMode from '@theme/Icon/DarkMode';
+import IconSystemColorMode from '@theme/Icon/SystemColorMode';
 import styles from './styles.module.css';
-function ColorModeToggle({className, buttonClassName, value, onChange}) {
-  const isBrowser = useIsBrowser();
-  const title = translate(
+// The order of color modes is defined here, and can be customized with swizzle
+function getNextColorMode(colorMode, respectPrefersColorScheme) {
+  // 2-value transition
+  if (!respectPrefersColorScheme) {
+    return colorMode === 'dark' ? 'light' : 'dark';
+  }
+  // 3-value transition
+  switch (colorMode) {
+    case null:
+      return 'light';
+    case 'light':
+      return 'dark';
+    case 'dark':
+      return null;
+    default:
+      throw new Error(`unexpected color mode ${colorMode}`);
+  }
+}
+function getColorModeLabel(colorMode) {
+  switch (colorMode) {
+    case null:
+      return translate({
+        message: 'system mode',
+        id: 'theme.colorToggle.ariaLabel.mode.system',
+        description: 'The name for the system color mode',
+      });
+    case 'light':
+      return translate({
+        message: 'light mode',
+        id: 'theme.colorToggle.ariaLabel.mode.light',
+        description: 'The name for the light color mode',
+      });
+    case 'dark':
+      return translate({
+        message: 'dark mode',
+        id: 'theme.colorToggle.ariaLabel.mode.dark',
+        description: 'The name for the dark color mode',
+      });
+    default:
+      throw new Error(`unexpected color mode ${colorMode}`);
+  }
+}
+function getColorModeAriaLabel(colorMode) {
+  return translate(
     {
       message: 'Switch between dark and light mode (currently {mode})',
       id: 'theme.colorToggle.ariaLabel',
-      description: 'The ARIA label for the navbar color mode toggle',
+      description: 'The ARIA label for the color mode toggle',
     },
     {
-      mode:
-        value === 'dark'
-          ? translate({
-              message: 'dark mode',
-              id: 'theme.colorToggle.ariaLabel.mode.dark',
-              description: 'The name for the dark color mode',
-            })
-          : translate({
-              message: 'light mode',
-              id: 'theme.colorToggle.ariaLabel.mode.light',
-              description: 'The name for the light color mode',
-            }),
+      mode: getColorModeLabel(colorMode),
     },
   );
+}
+function CurrentColorModeIcon() {
+  // 3 icons are always rendered for technical reasons
+  // We use "data-theme-choice" to render the correct one
+  // This must work even before React hydrates
+  return (
+    <>
+      <IconLightMode
+        // a18y is handled at the button level,
+        // not relying on button content (svg icons)
+        aria-hidden
+        className={clsx(styles.toggleIcon, styles.lightToggleIcon)}
+      />
+      <IconDarkMode
+        aria-hidden
+        className={clsx(styles.toggleIcon, styles.darkToggleIcon)}
+      />
+      <IconSystemColorMode
+        aria-hidden
+        className={clsx(styles.toggleIcon, styles.systemToggleIcon)}
+      />
+    </>
+  );
+}
+function ColorModeToggle({
+  className,
+  buttonClassName,
+  respectPrefersColorScheme,
+  value,
+  onChange,
+}) {
+  const isBrowser = useIsBrowser();
   return (
     <div className={clsx(styles.toggle, className)}>
       <button
@@ -44,18 +107,13 @@ function ColorModeToggle({className, buttonClassName, value, onChange}) {
           buttonClassName,
         )}
         type="button"
-        onClick={() => onChange(value === 'dark' ? 'light' : 'dark')}
+        onClick={() =>
+          onChange(getNextColorMode(value, respectPrefersColorScheme))
+        }
         disabled={!isBrowser}
-        title={title}
-        aria-label={title}
-        aria-live="polite"
-        aria-pressed={value === 'dark' ? 'true' : 'false'}>
-        <IconLightMode
-          className={clsx(styles.toggleIcon, styles.lightToggleIcon)}
-        />
-        <IconDarkMode
-          className={clsx(styles.toggleIcon, styles.darkToggleIcon)}
-        />
+        title={getColorModeLabel(value)}
+        aria-label={getColorModeAriaLabel(value)}>
+        <CurrentColorModeIcon />
       </button>
     </div>
   );

package/lib/theme/ColorModeToggle/styles.module.css

@@ -25,11 +25,16 @@
   background: var(--ifm-color-emphasis-200);
 }
 
-[data-theme='light'] .darkToggleIcon,
-[data-theme='dark'] .lightToggleIcon {
+.toggleIcon {
   display: none;
 }
 
+[data-theme-choice='system'] .systemToggleIcon,
+[data-theme-choice='light'] .lightToggleIcon,
+[data-theme-choice='dark'] .darkToggleIcon {
+  display: initial;
+}
+
 .toggleButtonDisabled {
   cursor: not-allowed;
 }

package/lib/theme/DocBreadcrumbs/StructuredData/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 { type ReactNode } from 'react';
+import type { Props } from '@theme/DocBreadcrumbs/StructuredData';
+export default function DocBreadcrumbsStructuredData(props: Props): ReactNode;

package/lib/theme/DocBreadcrumbs/StructuredData/index.js

@@ -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 Head from '@docusaurus/Head';
+import {useBreadcrumbsStructuredData} from '@docusaurus/plugin-content-docs/client';
+export default function DocBreadcrumbsStructuredData(props) {
+  const structuredData = useBreadcrumbsStructuredData({
+    breadcrumbs: props.breadcrumbs,
+  });
+  return (
+    <Head>
+      <script type="application/ld+json">
+        {JSON.stringify(structuredData)}
+      </script>
+    </Head>
+  );
+}

package/lib/theme/DocBreadcrumbs/index.js

@@ -12,44 +12,30 @@ import {useHomePageRoute} from '@docusaurus/theme-common/internal';
 import Link from '@docusaurus/Link';
 import {translate} from '@docusaurus/Translate';
 import HomeBreadcrumbItem from '@theme/DocBreadcrumbs/Items/Home';
+import DocBreadcrumbsStructuredData from '@theme/DocBreadcrumbs/StructuredData';
 import styles from './styles.module.css';
 // TODO move to design system folder
 function BreadcrumbsItemLink({children, href, isLast}) {
   const className = 'breadcrumbs__link';
   if (isLast) {
-    return (
-      <span className={className} itemProp="name">
-        {children}
-      </span>
-    );
+    return <span className={className}>{children}</span>;
   }
   return href ? (
-    <Link className={className} href={href} itemProp="item">
-      <span itemProp="name">{children}</span>
+    <Link className={className} href={href}>
+      <span>{children}</span>
     </Link>
   ) : (
-    // TODO Google search console doesn't like breadcrumb items without href.
-    // The schema doesn't seem to require `id` for each `item`, although Google
-    // insist to infer one, even if it's invalid. Removing `itemProp="item
-    // name"` for now, since I don't know how to properly fix it.
-    // See https://github.com/facebook/docusaurus/issues/7241
     <span className={className}>{children}</span>
   );
 }
 // TODO move to design system folder
-function BreadcrumbsItem({children, active, index, addMicrodata}) {
+function BreadcrumbsItem({children, active}) {
   return (
     <li
-      {...(addMicrodata && {
-        itemScope: true,
-        itemProp: 'itemListElement',
-        itemType: 'https://schema.org/ListItem',
-      })}
       className={clsx('breadcrumbs__item', {
         'breadcrumbs__item--active': active,
       })}>
       {children}
-      <meta itemProp="position" content={String(index + 1)} />
     </li>
   );
 }
@@ -60,40 +46,36 @@ export default function DocBreadcrumbs() {
     return null;
   }
   return (
-    <nav
-      className={clsx(
-        ThemeClassNames.docs.docBreadcrumbs,
-        styles.breadcrumbsContainer,
-      )}
-      aria-label={translate({
-        id: 'theme.docs.breadcrumbs.navAriaLabel',
-        message: 'Breadcrumbs',
-        description: 'The ARIA label for the breadcrumbs',
-      })}>
-      <ul
-        className="breadcrumbs"
-        itemScope
-        itemType="https://schema.org/BreadcrumbList">
-        {homePageRoute && <HomeBreadcrumbItem />}
-        {breadcrumbs.map((item, idx) => {
-          const isLast = idx === breadcrumbs.length - 1;
-          const href =
-            item.type === 'category' && item.linkUnlisted
-              ? undefined
-              : item.href;
-          return (
-            <BreadcrumbsItem
-              key={idx}
-              active={isLast}
-              index={idx}
-              addMicrodata={!!href}>
-              <BreadcrumbsItemLink href={href} isLast={isLast}>
-                {item.label}
-              </BreadcrumbsItemLink>
-            </BreadcrumbsItem>
-          );
-        })}
-      </ul>
-    </nav>
+    <>
+      <DocBreadcrumbsStructuredData breadcrumbs={breadcrumbs} />
+      <nav
+        className={clsx(
+          ThemeClassNames.docs.docBreadcrumbs,
+          styles.breadcrumbsContainer,
+        )}
+        aria-label={translate({
+          id: 'theme.docs.breadcrumbs.navAriaLabel',
+          message: 'Breadcrumbs',
+          description: 'The ARIA label for the breadcrumbs',
+        })}>
+        <ul className="breadcrumbs">
+          {homePageRoute && <HomeBreadcrumbItem />}
+          {breadcrumbs.map((item, idx) => {
+            const isLast = idx === breadcrumbs.length - 1;
+            const href =
+              item.type === 'category' && item.linkUnlisted
+                ? undefined
+                : item.href;
+            return (
+              <BreadcrumbsItem key={idx} active={isLast}>
+                <BreadcrumbsItemLink href={href} isLast={isLast}>
+                  {item.label}
+                </BreadcrumbsItemLink>
+              </BreadcrumbsItem>
+            );
+          })}
+        </ul>
+      </nav>
+    </>
   );
 }

package/lib/theme/DocCard/index.js

@@ -32,18 +32,18 @@ function useCategoryItemsPlural() {
       ),
     );
 }
-function CardContainer({href, children}) {
+function CardContainer({className, href, children}) {
   return (
     <Link
       href={href}
-      className={clsx('card padding--lg', styles.cardContainer)}>
+      className={clsx('card padding--lg', styles.cardContainer, className)}>
       {children}
     </Link>
   );
 }
-function CardLayout({href, icon, title, description}) {
+function CardLayout({className, href, icon, title, description}) {
   return (
-    <CardContainer href={href}>
+    <CardContainer href={href} className={className}>
       <Heading
         as="h2"
         className={clsx('text--truncate', styles.cardTitle)}
@@ -69,6 +69,7 @@ function CardCategory({item}) {
   }
   return (
     <CardLayout
+      className={item.className}
       href={href}
       icon="🗃️"
       title={item.label}
@@ -81,6 +82,7 @@ function CardLink({item}) {
   const doc = useDocById(item.docId ?? undefined);
   return (
     <CardLayout
+      className={item.className}
       href={item.href}
       icon={icon}
       title={item.label}

package/lib/theme/DocCardList/index.js

@@ -7,13 +7,21 @@
 import React from 'react';
 import clsx from 'clsx';
 import {
-  useCurrentSidebarCategory,
+  useCurrentSidebarSiblings,
   filterDocCardListItems,
 } from '@docusaurus/plugin-content-docs/client';
 import DocCard from '@theme/DocCard';
+import styles from './styles.module.css';
 function DocCardListForCurrentSidebarCategory({className}) {
-  const category = useCurrentSidebarCategory();
-  return <DocCardList items={category.items} className={className} />;
+  const items = useCurrentSidebarSiblings();
+  return <DocCardList items={items} className={className} />;
+}
+function DocCardListItem({item}) {
+  return (
+    <article className={clsx(styles.docCardListItem, 'col col--6')}>
+      <DocCard item={item} />
+    </article>
+  );
 }
 export default function DocCardList(props) {
   const {items, className} = props;
@@ -24,9 +32,7 @@ export default function DocCardList(props) {
   return (
     <section className={clsx('row', className)}>
       {filteredItems.map((item, index) => (
-        <article key={index} className="col col--6 margin-bottom--lg">
-          <DocCard item={item} />
-        </article>
+        <DocCardListItem key={index} item={item} />
       ))}
     </section>
   );

package/lib/theme/DocCardList/styles.module.css

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+
+.docCardListItem {
+  margin-bottom: 2rem;
+}
+
+.docCardListItem > * {
+  height: 100%;
+}

package/lib/theme/DocCategoryGeneratedIndexPage/index.js

@@ -44,7 +44,7 @@ function DocCategoryGeneratedIndexPageContent({categoryGeneratedIndex}) {
       <article className="margin-top--lg">
         <DocCardList items={category.items} className={styles.list} />
       </article>
-      <footer className="margin-top--lg">
+      <footer className="margin-top--md">
         <DocPaginator
           previous={categoryGeneratedIndex.navigation.previous}
           next={categoryGeneratedIndex.navigation.next}