@docusaurus/theme-classic 3.9.2 → 3.10.1

package/README.md

@@ -1,4 +1,4 @@
-# Docusaurus Theme Classic
+# `@docusaurus/theme-classic`
 
 The classic theme for Docusaurus.
 

package/lib/getSwizzleConfig.js

@@ -343,6 +343,13 @@ function getSwizzleConfig() {
                 },
                 description: 'The component used to render <img> tags and Markdown images in MDX',
             },
+            'MDXComponents/Li': {
+                actions: {
+                    eject: 'safe',
+                    wrap: 'safe',
+                },
+                description: 'The component used to render <li> tags in MDX',
+            },
             'MDXComponents/Pre': {
                 actions: {
                     eject: 'safe',

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

@@ -8,7 +8,7 @@ import React from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 import styles from './styles.module.css';
-function AdmonitionContainer({type, className, children}) {
+function AdmonitionContainer({type, className, children, id}) {
   return (
     <div
       className={clsx(
@@ -16,7 +16,8 @@ function AdmonitionContainer({type, className, children}) {
         ThemeClassNames.common.admonitionType(type),
         styles.admonition,
         className,
-      )}>
+      )}
+      id={id}>
       {children}
     </div>
   );
@@ -35,9 +36,9 @@ function AdmonitionContent({children}) {
   ) : null;
 }
 export default function AdmonitionLayout(props) {
-  const {type, icon, title, children, className} = props;
+  const {type, icon, title, children, className, id} = props;
   return (
-    <AdmonitionContainer type={type} className={className}>
+    <AdmonitionContainer type={type} className={className} id={id}>
       {title || icon ? <AdmonitionHeading title={title} icon={icon} /> : null}
       <AdmonitionContent>{children}</AdmonitionContent>
     </AdmonitionContainer>

package/lib/theme/CodeBlock/Buttons/CopyButton/index.js

@@ -32,6 +32,18 @@ function ariaLabel(isCopied) {
         description: 'The ARIA label for copy code blocks button',
       });
 }
+async function copyToClipboard(text) {
+  // The clipboard API is only defined in secure contexts (HTTPS / localhost).
+  // See https://developer.mozilla.org/en-US/docs/Web/API/Clipboard
+  if (navigator.clipboard) {
+    return navigator.clipboard.writeText(text);
+  }
+  // Fall back to copy-text-to-clipboard for non-secure contexts (e.g. HTTP
+  // on a local network). The fallback is lazily loaded to avoid bundle
+  // overhead for the common HTTPS case.
+  const {default: copy} = await import('copy-text-to-clipboard');
+  return copy(text);
+}
 function useCopyButton() {
   const {
     metadata: {code},
@@ -39,12 +51,14 @@ function useCopyButton() {
   const [isCopied, setIsCopied] = useState(false);
   const copyTimeout = useRef(undefined);
   const copyCode = useCallback(() => {
-    navigator.clipboard.writeText(code).then(() => {
+    copyToClipboard(code).then(() => {
       setIsCopied(true);
       copyTimeout.current = window.setTimeout(() => {
         setIsCopied(false);
       }, 1000);
     });
+    // Errors are intentionally not caught so they remain unhandled and can
+    // be captured by observability tools (e.g. Sentry, PostHog).
   }, [code]);
   useEffect(() => () => window.clearTimeout(copyTimeout.current), []);
   return {copyCode, isCopied};

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

@@ -8,8 +8,16 @@ 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 :/
+// This <br/ seems useful when the line has no content to prevent collapsing.
+// For code blocks with "diff" languages, this makes the empty lines collapse to
+// zero height lines, which is undesirable.
+// See also https://github.com/facebook/docusaurus/pull/11565
+function LineBreak() {
+  return <br />;
+}
+// Replaces single lines with '\n' by '' so that we don't end up with
+// duplicate line breaks (the '\n' + the artificial <br/> above)
+// see also https://github.com/facebook/docusaurus/pull/11565
 function fixLineBreak(line) {
   const singleLineBreakToken =
     line.length === 1 && line[0].content === '\n' ? line[0] : undefined;
@@ -39,7 +47,7 @@ export default function CodeBlockLine({
     );
   });
   return (
-    <span {...lineProps}>
+    <div {...lineProps}>
       {showLineNumbers ? (
         <>
           <span className={styles.codeLineNumber} />
@@ -48,7 +56,7 @@ export default function CodeBlockLine({
       ) : (
         lineTokens
       )}
-      <br />
-    </span>
+      <LineBreak />
+    </div>
   );
 }

package/lib/theme/DocCard/Description/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/DocCard/Description';
+export default function DocCardDescription({ description }: Props): ReactNode;

package/lib/theme/DocCard/Description/index.js

@@ -0,0 +1,23 @@
+/**
+ * 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 {ThemeClassNames} from '@docusaurus/theme-common';
+import styles from './styles.module.css';
+export default function DocCardDescription({description}) {
+  return (
+    <p
+      className={clsx(
+        'text--truncate',
+        ThemeClassNames.docs.docCard.description,
+        styles.cardDescription,
+      )}
+      title={description}>
+      {description}
+    </p>
+  );
+}

package/lib/theme/DocCard/Description/styles.module.css

@@ -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.
+ */
+
+.cardDescription {
+  font-size: 0.8rem;
+}

package/lib/theme/DocCard/Heading/Icon/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/DocCard/Heading/Icon';
+export default function DocCardHeadingIcon({ icon }: Props): ReactNode;

package/lib/theme/DocCard/Heading/Icon/index.js

@@ -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.
+ */
+import React from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import styles from './styles.module.css';
+export default function DocCardHeadingIcon({icon}) {
+  return (
+    <span
+      className={clsx(ThemeClassNames.docs.docCard.icon, styles.cardTitleIcon)}>
+      {icon}
+    </span>
+  );
+}

package/lib/theme/DocCard/Heading/Icon/styles.module.css

@@ -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.
+ */
+
+.cardTitleIcon {
+  font-size: 1.6rem;
+  margin-right: 0.6rem;
+}

package/lib/theme/DocCard/Heading/Text/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/DocCard/Heading/Text';
+export default function DocCardHeadingText({ title }: Props): ReactNode;

package/lib/theme/DocCard/Heading/Text/index.js

@@ -0,0 +1,22 @@
+/**
+ * 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 {ThemeClassNames} from '@docusaurus/theme-common';
+import styles from './styles.module.css';
+export default function DocCardHeadingText({title}) {
+  return (
+    <span
+      className={clsx(
+        'text--truncate',
+        ThemeClassNames.docs.docCard.title,
+        styles.cardTitleText,
+      )}>
+      {title}
+    </span>
+  );
+}

package/lib/theme/DocCard/Heading/Text/styles.module.css

@@ -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.
+ */
+
+.cardTitleText {
+  font-size: 1.2rem;
+}

package/lib/theme/DocCard/Heading/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/DocCard/Heading';
+export default function DocCardHeading({ item, title, icon }: Props): ReactNode;

package/lib/theme/DocCard/Heading/index.js

@@ -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 from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import Heading from '@theme/Heading';
+import Icon from '@theme/DocCard/Heading/Icon';
+import Text from '@theme/DocCard/Heading/Text';
+import styles from './styles.module.css';
+export default function DocCardHeading({item, title, icon}) {
+  return (
+    <Heading
+      as="h2"
+      className={clsx(ThemeClassNames.docs.docCard.heading, styles.cardTitle)}
+      title={title}>
+      {icon && <Icon item={item} icon={icon} />}
+      <Text item={item} title={title} />
+    </Heading>
+  );
+}

package/lib/theme/DocCard/Heading/styles.module.css

@@ -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.
+ */
+
+.cardTitle {
+  display: inline-flex;
+  align-items: center;
+}

package/lib/theme/DocCard/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/DocCard/Layout';
+export default function DocCardLayout({ item, className, href, icon, title, description, }: Props): ReactNode;

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

@@ -0,0 +1,42 @@
+/**
+ * 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 Link from '@docusaurus/Link';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import Heading from '@theme/DocCard/Heading';
+import Description from '@theme/DocCard/Description';
+import styles from './styles.module.css';
+function Container({className, href, children}) {
+  return (
+    <Link
+      href={href}
+      className={clsx(
+        'card padding--lg',
+        ThemeClassNames.docs.docCard.container,
+        styles.cardContainer,
+        className,
+      )}>
+      {children}
+    </Link>
+  );
+}
+export default function DocCardLayout({
+  item,
+  className,
+  href,
+  icon,
+  title,
+  description,
+}) {
+  return (
+    <Container href={href} className={className}>
+      <Heading item={item} icon={icon} title={title} />
+      {description && <Description item={item} description={description} />}
+    </Container>
+  );
+}

package/lib/theme/DocCard/{styles.module.css → Layout/styles.module.css}

@@ -24,11 +24,3 @@
 .cardContainer *:last-child {
   margin-bottom: 0;
 }
-
-.cardTitle {
-  font-size: 1.2rem;
-}
-
-.cardDescription {
-  font-size: 0.8rem;
-}

package/lib/theme/DocCard/index.js

@@ -5,88 +5,56 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import clsx from 'clsx';
-import Link from '@docusaurus/Link';
 import {
   useDocById,
   findFirstSidebarItemLink,
 } from '@docusaurus/plugin-content-docs/client';
-import {usePluralForm} from '@docusaurus/theme-common';
+import {
+  extractLeadingEmoji,
+  useDocCardDescriptionCategoryItemsPlural,
+} from '@docusaurus/theme-common/internal';
 import isInternalUrl from '@docusaurus/isInternalUrl';
-import {translate} from '@docusaurus/Translate';
-import Heading from '@theme/Heading';
-import styles from './styles.module.css';
-function useCategoryItemsPlural() {
-  const {selectMessage} = usePluralForm();
-  return (count) =>
-    selectMessage(
-      count,
-      translate(
-        {
-          message: '1 item|{count} items',
-          id: 'theme.docs.DocCard.categoryDescription.plurals',
-          description:
-            'The default description for a category card in the generated index about how many items this category includes',
-        },
-        {count},
-      ),
-    );
-}
-function CardContainer({className, href, children}) {
-  return (
-    <Link
-      href={href}
-      className={clsx('card padding--lg', styles.cardContainer, className)}>
-      {children}
-    </Link>
-  );
+import Layout from '@theme/DocCard/Layout';
+function getFallbackEmojiIcon(item) {
+  if (item.type === 'category') {
+    return '🗃';
+  }
+  return isInternalUrl(item.href) ? '📄️' : '🔗';
 }
-function CardLayout({className, href, icon, title, description}) {
-  return (
-    <CardContainer href={href} className={className}>
-      <Heading
-        as="h2"
-        className={clsx('text--truncate', styles.cardTitle)}
-        title={title}>
-        {icon} {title}
-      </Heading>
-      {description && (
-        <p
-          className={clsx('text--truncate', styles.cardDescription)}
-          title={description}>
-          {description}
-        </p>
-      )}
-    </CardContainer>
-  );
+function getIconTitleProps(item) {
+  const extracted = extractLeadingEmoji(item.label);
+  const emoji = extracted.emoji ?? getFallbackEmojiIcon(item);
+  return {
+    icon: emoji,
+    title: extracted.rest.trim(),
+  };
 }
 function CardCategory({item}) {
   const href = findFirstSidebarItemLink(item);
-  const categoryItemsPlural = useCategoryItemsPlural();
+  const categoryItemsPlural = useDocCardDescriptionCategoryItemsPlural();
   // Unexpected: categories that don't have a link have been filtered upfront
   if (!href) {
     return null;
   }
   return (
-    <CardLayout
+    <Layout
+      item={item}
       className={item.className}
       href={href}
-      icon="🗃️"
-      title={item.label}
       description={item.description ?? categoryItemsPlural(item.items.length)}
+      {...getIconTitleProps(item)}
     />
   );
 }
 function CardLink({item}) {
-  const icon = isInternalUrl(item.href) ? '📄️' : '🔗';
   const doc = useDocById(item.docId ?? undefined);
   return (
-    <CardLayout
+    <Layout
+      item={item}
       className={item.className}
       href={item.href}
-      icon={icon}
-      title={item.label}
       description={item.description ?? doc?.description}
+      {...getIconTitleProps(item)}
     />
   );
 }

package/lib/theme/Layout/index.js

@@ -12,7 +12,6 @@ import {
   SkipToContentFallbackId,
   ThemeClassNames,
 } from '@docusaurus/theme-common';
-import {useKeyboardNavigation} from '@docusaurus/theme-common/internal';
 import SkipToContent from '@theme/SkipToContent';
 import AnnouncementBar from '@theme/AnnouncementBar';
 import Navbar from '@theme/Navbar';
@@ -29,7 +28,6 @@ export default function Layout(props) {
     title,
     description,
   } = props;
-  useKeyboardNavigation();
   return (
     <LayoutProvider>
       <PageMetadata title={title} description={description} />

package/lib/theme/Navbar/MobileSidebar/Layout/index.js

@@ -14,6 +14,7 @@ import {ThemeClassNames} from '@docusaurus/theme-common';
 function inertProps(inert) {
   const isBeforeReact19 = parseInt(version.split('.')[0], 10) < 19;
   if (isBeforeReact19) {
+    // TODO Docusaurus v4: remove temporary inert workaround
     return {inert: inert ? '' : undefined};
   }
   return {inert};

package/lib/theme/NavbarItem/DropdownNavbarItem/Desktop/index.js

@@ -52,7 +52,7 @@ export default function DropdownNavbarItemDesktop({
         {...props}
         onClick={props.to ? undefined : (e) => e.preventDefault()}
         onKeyDown={(e) => {
-          if (e.key === 'Enter') {
+          if (e.key === 'Enter' || e.key === ' ') {
             e.preventDefault();
             setShowDropdown(!showDropdown);
           }

package/lib/theme/SiteMetadata/index.js

@@ -12,7 +12,6 @@ import {PageMetadata, useThemeConfig} from '@docusaurus/theme-common';
 import {
   DEFAULT_SEARCH_TAG,
   useAlternatePageUtils,
-  keyboardFocusedClassName,
 } from '@docusaurus/theme-common/internal';
 import {useLocation} from '@docusaurus/router';
 import {applyTrailingSlash} from '@docusaurus/utils-common';
@@ -115,7 +114,7 @@ export default function SiteMetadata() {
         <meta name="twitter:card" content="summary_large_image" />
         {/* The keyboard focus class name need to be applied when SSR so links
         are outlined when JS is disabled */}
-        <body className={keyboardFocusedClassName} />
+        <body />
       </Head>
 
       {defaultImage && <PageMetadata image={defaultImage} />}

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

@@ -6,4 +6,4 @@
  */
 import { type ReactNode } from 'react';
 import type { Props } from '@theme/TabItem';
-export default function TabItem({ children, hidden, className, }: Props): ReactNode;
+export default function TabItem({ children, className, value, }: Props): ReactNode;

package/lib/theme/TabItem/index.js

@@ -6,8 +6,9 @@
  */
 import React from 'react';
 import clsx from 'clsx';
+import {useTabs} from '@docusaurus/theme-common/internal';
 import styles from './styles.module.css';
-export default function TabItem({children, hidden, className}) {
+function TabItemPanel({children, className, hidden}) {
   return (
     <div
       role="tabpanel"
@@ -17,3 +18,16 @@ export default function TabItem({children, hidden, className}) {
     </div>
   );
 }
+export default function TabItem({children, className, value}) {
+  const {selectedValue, lazy} = useTabs();
+  const isSelected = value === selectedValue;
+  // TODO Docusaurus v4: use <Activity> ?
+  if (!isSelected && lazy) {
+    return null;
+  }
+  return (
+    <TabItemPanel className={className} hidden={!isSelected}>
+      {children}
+    </TabItemPanel>
+  );
+}