@docusaurus/theme-classic 3.9.2 → 3.10.1

package/lib/theme/Tabs/index.js

@@ -4,17 +4,20 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, {cloneElement} from 'react';
+import React from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 import {
   useScrollPositionBlocker,
+  useTabsContextValue,
   useTabs,
   sanitizeTabsChildren,
+  TabsProvider,
 } from '@docusaurus/theme-common/internal';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import styles from './styles.module.css';
-function TabList({className, block, selectedValue, selectValue, tabValues}) {
+function TabList({className}) {
+  const {selectedValue, selectValue, tabValues, block} = useTabs();
   const tabRefs = [];
   const {blockElementScrollPositionUntilNextRender} =
     useScrollPositionBlocker();
@@ -67,8 +70,8 @@ function TabList({className, block, selectedValue, selectValue, tabValues}) {
           tabIndex={selectedValue === value ? 0 : -1}
           aria-selected={selectedValue === value}
           key={value}
-          ref={(tabControl) => {
-            tabRefs.push(tabControl);
+          ref={(ref) => {
+            tabRefs.push(ref);
           }}
           onKeyDown={handleKeydown}
           onClick={handleTabChange}
@@ -82,35 +85,10 @@ function TabList({className, block, selectedValue, selectValue, tabValues}) {
     </ul>
   );
 }
-function TabContent({lazy, children, selectedValue}) {
-  const childTabs = (Array.isArray(children) ? children : [children]).filter(
-    Boolean,
-  );
-  if (lazy) {
-    const selectedTabItem = childTabs.find(
-      (tabItem) => tabItem.props.value === selectedValue,
-    );
-    if (!selectedTabItem) {
-      // fail-safe or fail-fast? not sure what's best here
-      return null;
-    }
-    return cloneElement(selectedTabItem, {
-      className: clsx('margin-top--md', selectedTabItem.props.className),
-    });
-  }
-  return (
-    <div className="margin-top--md">
-      {childTabs.map((tabItem, i) =>
-        cloneElement(tabItem, {
-          key: i,
-          hidden: tabItem.props.value !== selectedValue,
-        }),
-      )}
-    </div>
-  );
+function TabContent({children}) {
+  return <div className="margin-top--md">{children}</div>;
 }
-function TabsComponent(props) {
-  const tabs = useTabs(props);
+function TabsContainer({className, children}) {
   return (
     <div
       className={clsx(
@@ -120,20 +98,27 @@ function TabsComponent(props) {
         'tabs-container',
         styles.tabList,
       )}>
-      <TabList {...tabs} {...props} />
-      <TabContent {...tabs} {...props} />
+      <TabList
+        // Surprising but historical
+        // className is applied on TabList, not on TabsContainer
+        className={className}
+      />
+      <TabContent>{children}</TabContent>
     </div>
   );
 }
 export default function Tabs(props) {
   const isBrowser = useIsBrowser();
+  const value = useTabsContextValue(props);
   return (
-    <TabsComponent
+    <TabsProvider
+      value={value}
       // Remount tabs after hydration
       // Temporary fix for https://github.com/facebook/docusaurus/issues/5653
-      key={String(isBrowser)}
-      {...props}>
-      {sanitizeTabsChildren(props.children)}
-    </TabsComponent>
+      key={String(isBrowser)}>
+      <TabsContainer className={props.className}>
+        {sanitizeTabsChildren(props.children)}
+      </TabsContainer>
+    </TabsProvider>
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "3.9.2",
+  "version": "3.10.1",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -20,21 +20,22 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docusaurus/core": "3.9.2",
-    "@docusaurus/logger": "3.9.2",
-    "@docusaurus/mdx-loader": "3.9.2",
-    "@docusaurus/module-type-aliases": "3.9.2",
-    "@docusaurus/plugin-content-blog": "3.9.2",
-    "@docusaurus/plugin-content-docs": "3.9.2",
-    "@docusaurus/plugin-content-pages": "3.9.2",
-    "@docusaurus/theme-common": "3.9.2",
-    "@docusaurus/theme-translations": "3.9.2",
-    "@docusaurus/types": "3.9.2",
-    "@docusaurus/utils": "3.9.2",
-    "@docusaurus/utils-common": "3.9.2",
-    "@docusaurus/utils-validation": "3.9.2",
+    "@docusaurus/core": "3.10.1",
+    "@docusaurus/logger": "3.10.1",
+    "@docusaurus/mdx-loader": "3.10.1",
+    "@docusaurus/module-type-aliases": "3.10.1",
+    "@docusaurus/plugin-content-blog": "3.10.1",
+    "@docusaurus/plugin-content-docs": "3.10.1",
+    "@docusaurus/plugin-content-pages": "3.10.1",
+    "@docusaurus/theme-common": "3.10.1",
+    "@docusaurus/theme-translations": "3.10.1",
+    "@docusaurus/types": "3.10.1",
+    "@docusaurus/utils": "3.10.1",
+    "@docusaurus/utils-common": "3.10.1",
+    "@docusaurus/utils-validation": "3.10.1",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
+    "copy-text-to-clipboard": "^3.2.0",
     "infima": "0.2.0-alpha.45",
     "lodash": "^4.17.21",
     "nprogress": "^0.2.0",
@@ -51,7 +52,6 @@
     "@types/prismjs": "^1.26.0",
     "@types/rtlcss": "^3.5.1",
     "fs-extra": "^11.1.1",
-    "react-test-renderer": "^18.0.0",
     "utility-types": "^3.10.0"
   },
   "peerDependencies": {
@@ -61,5 +61,5 @@
   "engines": {
     "node": ">=20.0"
   },
-  "gitHead": "abfbe5621b08407bc3dcbe6111ff118d4c22f7a1"
+  "gitHead": "41c1a458ecb07d61b6df2761ea4bc1b13db49d12"
 }

package/src/getSwizzleConfig.ts

@@ -368,6 +368,13 @@ export default function getSwizzleConfig(): SwizzleConfig {
         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/src/theme/Admonition/Layout/index.tsx

@@ -17,7 +17,8 @@ function AdmonitionContainer({
   type,
   className,
   children,
-}: Pick<Props, 'type' | 'className'> & {children: ReactNode}) {
+  id,
+}: Pick<Props, 'type' | 'className' | 'id'> & {children: ReactNode}) {
   return (
     <div
       className={clsx(
@@ -25,7 +26,8 @@ function AdmonitionContainer({
         ThemeClassNames.common.admonitionType(type),
         styles.admonition,
         className,
-      )}>
+      )}
+      id={id}>
       {children}
     </div>
   );
@@ -47,9 +49,9 @@ function AdmonitionContent({children}: Pick<Props, 'children'>) {
 }
 
 export default function AdmonitionLayout(props: Props): ReactNode {
-  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/src/theme/CodeBlock/Buttons/CopyButton/index.tsx

@@ -44,6 +44,19 @@ function ariaLabel(isCopied: boolean) {
       });
 }
 
+async function copyToClipboard(text: string) {
+  // 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},
@@ -52,12 +65,14 @@ function useCopyButton() {
   const copyTimeout = useRef<number | undefined>(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), []);

package/src/theme/CodeBlock/Line/index.tsx

@@ -14,16 +14,23 @@ import styles from './styles.module.css';
 
 type Token = Props['line'][number];
 
-// 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: Token[]) {
   const singleLineBreakToken =
     line.length === 1 && line[0]!.content === '\n' ? line[0] : undefined;
-
   if (singleLineBreakToken) {
     return [{...singleLineBreakToken, content: ''}];
   }
-
   return line;
 }
 
@@ -35,7 +42,6 @@ export default function CodeBlockLine({
   getTokenProps,
 }: Props): ReactNode {
   const line = fixLineBreak(lineProp);
-
   const lineProps = getLineProps({
     line,
     className: clsx(classNames, showLineNumbers && styles.codeLine),
@@ -51,7 +57,7 @@ export default function CodeBlockLine({
   });
 
   return (
-    <span {...lineProps}>
+    <div {...lineProps}>
       {showLineNumbers ? (
         <>
           <span className={styles.codeLineNumber} />
@@ -60,7 +66,7 @@ export default function CodeBlockLine({
       ) : (
         lineTokens
       )}
-      <br />
-    </span>
+      <LineBreak />
+    </div>
   );
 }

package/src/theme/DocCard/Description/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, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import type {Props} from '@theme/DocCard/Description';
+
+import styles from './styles.module.css';
+
+export default function DocCardDescription({description}: Props): ReactNode {
+  return (
+    <p
+      className={clsx(
+        'text--truncate',
+        ThemeClassNames.docs.docCard.description,
+        styles.cardDescription,
+      )}
+      title={description}>
+      {description}
+    </p>
+  );
+}

package/src/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/src/theme/DocCard/Heading/Icon/index.tsx

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

package/src/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/src/theme/DocCard/Heading/Text/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, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import type {Props} from '@theme/DocCard/Heading/Text';
+
+import styles from './styles.module.css';
+
+export default function DocCardHeadingText({title}: Props): ReactNode {
+  return (
+    <span
+      className={clsx(
+        'text--truncate',
+
+        ThemeClassNames.docs.docCard.title,
+        styles.cardTitleText,
+      )}>
+      {title}
+    </span>
+  );
+}

package/src/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/src/theme/DocCard/Heading/index.tsx

@@ -0,0 +1,28 @@
+/**
+ * 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 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 type {Props} from '@theme/DocCard/Heading';
+
+import styles from './styles.module.css';
+
+export default function DocCardHeading({item, title, icon}: Props): ReactNode {
+  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/src/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/src/theme/DocCard/Layout/index.tsx

@@ -0,0 +1,55 @@
+/**
+ * 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 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 type {Props} from '@theme/DocCard/Layout';
+
+import styles from './styles.module.css';
+
+function Container({
+  className,
+  href,
+  children,
+}: {
+  className?: string;
+  href: string;
+  children: ReactNode;
+}): ReactNode {
+  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,
+}: Props): ReactNode {
+  return (
+    <Container href={href} className={className}>
+      <Heading item={item} icon={icon} title={title} />
+      {description && <Description item={item} description={description} />}
+    </Container>
+  );
+}

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

@@ -6,122 +6,71 @@
  */
 
 import React, {type ReactNode} 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 Layout from '@theme/DocCard/Layout';
 
 import type {Props} from '@theme/DocCard';
-import Heading from '@theme/Heading';
 import type {
   PropSidebarItemCategory,
   PropSidebarItemLink,
 } from '@docusaurus/plugin-content-docs';
 
-import styles from './styles.module.css';
-
-function useCategoryItemsPlural() {
-  const {selectMessage} = usePluralForm();
-  return (count: number) =>
-    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,
-}: {
-  className?: string;
-  href: string;
-  children: ReactNode;
-}): ReactNode {
-  return (
-    <Link
-      href={href}
-      className={clsx('card padding--lg', styles.cardContainer, className)}>
-      {children}
-    </Link>
-  );
+function getFallbackEmojiIcon(
+  item: PropSidebarItemLink | PropSidebarItemCategory,
+): string {
+  if (item.type === 'category') {
+    return '🗃';
+  }
+  return isInternalUrl(item.href) ? '📄️' : '🔗';
 }
 
-function CardLayout({
-  className,
-  href,
-  icon,
-  title,
-  description,
-}: {
-  className?: string;
-  href: string;
-  icon: ReactNode;
-  title: string;
-  description?: string;
-}): ReactNode {
-  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: PropSidebarItemLink | PropSidebarItemCategory,
+): {icon: ReactNode; title: string} {
+  const extracted = extractLeadingEmoji(item.label);
+  const emoji = extracted.emoji ?? getFallbackEmojiIcon(item);
+  return {
+    icon: emoji,
+    title: extracted.rest.trim(),
+  };
 }
 
 function CardCategory({item}: {item: PropSidebarItemCategory}): ReactNode {
   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}: {item: PropSidebarItemLink}): ReactNode {
-  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)}
     />
   );
 }