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

package/src/theme/ColorModeToggle/index.tsx

@@ -11,40 +11,105 @@ 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 type {Props} from '@theme/ColorModeToggle';
+import type {ColorMode} from '@docusaurus/theme-common';
 
 import styles from './styles.module.css';
 
-function ColorModeToggle({
-  className,
-  buttonClassName,
-  value,
-  onChange,
-}: Props): ReactNode {
-  const isBrowser = useIsBrowser();
+// The order of color modes is defined here, and can be customized with swizzle
+function getNextColorMode(
+  colorMode: ColorMode | null,
+  respectPrefersColorScheme: boolean,
+) {
+  // 2-value transition
+  if (!respectPrefersColorScheme) {
+    return colorMode === 'dark' ? 'light' : 'dark';
+  }
 
-  const title = translate(
+  // 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: ColorMode | null): string {
+  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: ColorMode | null) {
+  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(): ReactNode {
+  // 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,
+}: Props): ReactNode {
+  const isBrowser = useIsBrowser();
   return (
     <div className={clsx(styles.toggle, className)}>
       <button
@@ -55,18 +120,23 @@ function ColorModeToggle({
           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)}
+
+        // For accessibility decisions
+        // See https://github.com/facebook/docusaurus/issues/7667#issuecomment-2724401796
+
+        // aria-live disabled on purpose - This is annoying because:
+        // - without this attribute, VoiceOver doesn't announce on button enter
+        // - with this attribute, VoiceOver announces twice on ctrl+opt+space
+        // - with this attribute, NVDA announces many times
+        // aria-live="polite"
+      >
+        <CurrentColorModeIcon />
       </button>
     </div>
   );

package/src/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/src/theme/DocBreadcrumbs/StructuredData/index.tsx

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

package/src/theme/DocBreadcrumbs/index.tsx

@@ -13,6 +13,7 @@ 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';
 
@@ -28,22 +29,13 @@ function BreadcrumbsItemLink({
 }): ReactNode {
   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>
   );
 }
@@ -52,26 +44,16 @@ function BreadcrumbsItemLink({
 function BreadcrumbsItem({
   children,
   active,
-  index,
-  addMicrodata,
 }: {
   children: ReactNode;
   active?: boolean;
-  index: number;
-  addMicrodata: boolean;
 }): ReactNode {
   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>
   );
 }
@@ -85,40 +67,36 @@ export default function DocBreadcrumbs(): ReactNode {
   }
 
   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/src/theme/DocCard/index.tsx

@@ -43,34 +43,38 @@ function useCategoryItemsPlural() {
 }
 
 function CardContainer({
+  className,
   href,
   children,
 }: {
+  className?: string;
   href: string;
   children: ReactNode;
 }): ReactNode {
   return (
     <Link
       href={href}
-      className={clsx('card padding--lg', styles.cardContainer)}>
+      className={clsx('card padding--lg', styles.cardContainer, className)}>
       {children}
     </Link>
   );
 }
 
 function CardLayout({
+  className,
   href,
   icon,
   title,
   description,
 }: {
+  className?: string;
   href: string;
   icon: ReactNode;
   title: string;
   description?: string;
 }): ReactNode {
   return (
-    <CardContainer href={href}>
+    <CardContainer href={href} className={className}>
       <Heading
         as="h2"
         className={clsx('text--truncate', styles.cardTitle)}
@@ -99,6 +103,7 @@ function CardCategory({item}: {item: PropSidebarItemCategory}): ReactNode {
 
   return (
     <CardLayout
+      className={item.className}
       href={href}
       icon="🗃️"
       title={item.label}
@@ -112,6 +117,7 @@ function CardLink({item}: {item: PropSidebarItemLink}): ReactNode {
   const doc = useDocById(item.docId ?? undefined);
   return (
     <CardLayout
+      className={item.className}
       href={item.href}
       icon={icon}
       title={item.label}

package/src/theme/DocCardList/index.tsx

@@ -5,18 +5,31 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {type ReactNode} from 'react';
+import React, {type ComponentProps, type ReactNode} from 'react';
 import clsx from 'clsx';
 import {
-  useCurrentSidebarCategory,
+  useCurrentSidebarSiblings,
   filterDocCardListItems,
 } from '@docusaurus/plugin-content-docs/client';
 import DocCard from '@theme/DocCard';
 import type {Props} from '@theme/DocCardList';
+import styles from './styles.module.css';
 
 function DocCardListForCurrentSidebarCategory({className}: Props) {
-  const category = useCurrentSidebarCategory();
-  return <DocCardList items={category.items} className={className} />;
+  const items = useCurrentSidebarSiblings();
+  return <DocCardList items={items} className={className} />;
+}
+
+function DocCardListItem({
+  item,
+}: {
+  item: ComponentProps<typeof DocCard>['item'];
+}) {
+  return (
+    <article className={clsx(styles.docCardListItem, 'col col--6')}>
+      <DocCard item={item} />
+    </article>
+  );
 }
 
 export default function DocCardList(props: Props): ReactNode {
@@ -28,9 +41,7 @@ export default function DocCardList(props: Props): ReactNode {
   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/src/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/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -53,7 +53,7 @@ function DocCategoryGeneratedIndexPageContent({
       <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}

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

@@ -9,10 +9,6 @@
   .generatedIndexPage {
     max-width: 75% !important;
   }
-
-  .list article:nth-last-child(-n + 2) {
-    margin-bottom: 0 !important;
-  }
 }
 
 /* Duplicated from .markdown h1 */
@@ -20,7 +16,3 @@
   --ifm-h1-font-size: 3rem;
   margin-bottom: calc(1.25 * var(--ifm-leading));
 }
-
-.list article:last-child {
-  margin-bottom: 0 !important;
-}

package/src/theme/DocItem/Paginator/index.tsx

@@ -15,5 +15,11 @@ import DocPaginator from '@theme/DocPaginator';
  */
 export default function DocItemPaginator(): ReactNode {
   const {metadata} = useDoc();
-  return <DocPaginator previous={metadata.previous} next={metadata.next} />;
+  return (
+    <DocPaginator
+      className="docusaurus-mt-lg"
+      previous={metadata.previous}
+      next={metadata.next}
+    />
+  );
 }

package/src/theme/DocPaginator/index.tsx

@@ -6,15 +6,16 @@
  */
 
 import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
 import Translate, {translate} from '@docusaurus/Translate';
 import PaginatorNavLink from '@theme/PaginatorNavLink';
 import type {Props} from '@theme/DocPaginator';
 
 export default function DocPaginator(props: Props): ReactNode {
-  const {previous, next} = props;
+  const {className, previous, next} = props;
   return (
     <nav
-      className="pagination-nav docusaurus-mt-lg"
+      className={clsx(className, 'pagination-nav')}
       aria-label={translate({
         id: 'theme.docs.paginator.navAriaLabel',
         message: 'Docs pages',

package/src/theme/DocSidebarItem/Category/index.tsx

@@ -188,7 +188,14 @@ export default function DocSidebarItemCategory({
               ? (e) => {
                   onItemClick?.(item);
                   if (href) {
-                    updateCollapsed(false);
+                    if (isActive) {
+                      e.preventDefault();
+                      updateCollapsed();
+                    } else {
+                      // When navigating to a new category, we always expand
+                      // see https://github.com/facebook/docusaurus/issues/10854#issuecomment-2609616182
+                      updateCollapsed(false);
+                    }
                   } else {
                     e.preventDefault();
                     updateCollapsed();

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

@@ -7,6 +7,7 @@
 
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 import type {Props} from '@theme/Footer/Layout';
 
 export default function FooterLayout({
@@ -17,7 +18,7 @@ export default function FooterLayout({
 }: Props): ReactNode {
   return (
     <footer
-      className={clsx('footer', {
+      className={clsx(ThemeClassNames.layout.footer.container, 'footer', {
         'footer--dark': style === 'dark',
       })}>
       <div className="container container-fluid">

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

@@ -7,6 +7,7 @@
 
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 import LinkItem from '@theme/Footer/LinkItem';
 import type {Props} from '@theme/Footer/Links/MultiColumn';
 
@@ -30,7 +31,12 @@ function ColumnLinkItem({item}: {item: ColumnItemType}) {
 
 function Column({column}: {column: ColumnType}) {
   return (
-    <div className={clsx('col footer__col', column.className)}>
+    <div
+      className={clsx(
+        ThemeClassNames.layout.footer.column,
+        'col footer__col',
+        column.className,
+      )}>
       <div className="footer__title">{column.title}</div>
       <ul className="footer__items clean-list">
         {column.items.map((item, i) => (

package/src/theme/Icon/ExternalLink/index.tsx

@@ -10,6 +10,10 @@ import type {Props} from '@theme/Icon/ExternalLink';
 
 import styles from './styles.module.css';
 
+// References symbol in docusaurus-theme-classic/src/inlineSvgSprites.ts
+// See why: https://github.com/facebook/docusaurus/issues/5865
+const svgSprite = '#theme-svg-external-link';
+
 export default function IconExternalLink({
   width = 13.5,
   height = 13.5,
@@ -19,12 +23,8 @@ export default function IconExternalLink({
       width={width}
       height={height}
       aria-hidden="true"
-      viewBox="0 0 24 24"
       className={styles.iconExternalLink}>
-      <path
-        fill="currentColor"
-        d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"
-      />
+      <use href={svgSprite} />
     </svg>
   );
 }

package/src/theme/Icon/SystemColorMode/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 type {ReactNode} from 'react';
+import type {Props} from '@theme/Icon/SystemColorMode';
+
+export default function IconSystemColorMode(props: Props): ReactNode {
+  return (
+    <svg viewBox="0 0 24 24" width={24} height={24} {...props}>
+      <path
+        fill="currentColor"
+        d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"
+      />
+    </svg>
+  );
+}

package/src/theme/Layout/index.tsx

@@ -48,6 +48,7 @@ export default function Layout(props: Props): ReactNode {
       <div
         id={SkipToContentFallbackId}
         className={clsx(
+          ThemeClassNames.layout.main.container,
           ThemeClassNames.wrapper.main,
           styles.mainWrapper,
           wrapperClassName,

package/src/theme/Navbar/ColorModeToggle/index.tsx

@@ -13,10 +13,10 @@ import styles from './styles.module.css';
 
 export default function NavbarColorModeToggle({className}: Props): ReactNode {
   const navbarStyle = useThemeConfig().navbar.style;
-  const disabled = useThemeConfig().colorMode.disableSwitch;
-  const {colorMode, setColorMode} = useColorMode();
+  const {disableSwitch, respectPrefersColorScheme} = useThemeConfig().colorMode;
+  const {colorModeChoice, setColorMode} = useColorMode();
 
-  if (disabled) {
+  if (disableSwitch) {
     return null;
   }
 
@@ -26,7 +26,8 @@ export default function NavbarColorModeToggle({className}: Props): ReactNode {
       buttonClassName={
         navbarStyle === 'dark' ? styles.darkNavbarColorModeToggle : undefined
       }
-      value={colorMode}
+      respectPrefersColorScheme={respectPrefersColorScheme}
+      value={colorModeChoice}
       onChange={setColorMode}
     />
   );