@docusaurus/theme-classic 3.9.2 → 3.10.1-canary-6591

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)}
     />
   );
 }

package/src/theme/Layout/index.tsx

@@ -13,7 +13,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';
@@ -33,8 +32,6 @@ export default function Layout(props: Props): ReactNode {
     description,
   } = props;
 
-  useKeyboardNavigation();
-
   return (
     <LayoutProvider>
       <PageMetadata title={title} description={description} />

package/src/theme/Navbar/MobileSidebar/Layout/index.tsx

@@ -17,7 +17,8 @@ import type {Props} from '@theme/Navbar/MobileSidebar/Layout';
 function inertProps(inert: boolean) {
   const isBeforeReact19 = parseInt(version!.split('.')[0]!, 10) < 19;
   if (isBeforeReact19) {
-    return {inert: inert ? '' : undefined};
+    // TODO Docusaurus v4: remove temporary inert workaround
+    return {inert: inert ? '' : undefined} as unknown as {inert: boolean};
   }
   return {inert};
 }

package/src/theme/NavbarItem/DropdownNavbarItem/Desktop/index.tsx

@@ -64,7 +64,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/src/theme/SiteMetadata/index.tsx

@@ -13,7 +13,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';
@@ -130,7 +129,7 @@ export default function SiteMetadata(): ReactNode {
         <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/src/theme/TabItem/index.tsx

@@ -7,15 +7,20 @@
 
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
+import {useTabs} from '@docusaurus/theme-common/internal';
 import type {Props} from '@theme/TabItem';
 
 import styles from './styles.module.css';
 
-export default function TabItem({
+function TabItemPanel({
   children,
-  hidden,
   className,
-}: Props): ReactNode {
+  hidden,
+}: {
+  children: ReactNode;
+  className?: string;
+  hidden?: boolean;
+}) {
   return (
     <div
       role="tabpanel"
@@ -25,3 +30,23 @@ export default function TabItem({
     </div>
   );
 }
+
+export default function TabItem({
+  children,
+  className,
+  value,
+}: Props): ReactNode {
+  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>
+  );
+}

package/src/theme/Tabs/index.tsx

@@ -5,26 +5,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {cloneElement, type ReactElement, type ReactNode} from 'react';
+import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 import {
   useScrollPositionBlocker,
+  useTabsContextValue,
   useTabs,
   sanitizeTabsChildren,
-  type TabItemProps,
+  TabsProvider,
 } from '@docusaurus/theme-common/internal';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import type {Props} from '@theme/Tabs';
 import styles from './styles.module.css';
 
-function TabList({
-  className,
-  block,
-  selectedValue,
-  selectValue,
-  tabValues,
-}: Props & ReturnType<typeof useTabs>) {
+function TabList({className}: {className?: string}) {
+  const {selectedValue, selectValue, tabValues, block} = useTabs();
+
   const tabRefs: (HTMLLIElement | null)[] = [];
   const {blockElementScrollPositionUntilNextRender} =
     useScrollPositionBlocker();
@@ -88,8 +85,8 @@ function TabList({
           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}
@@ -109,40 +106,17 @@ function TabList({
   );
 }
 
-function TabContent({
-  lazy,
-  children,
-  selectedValue,
-}: Props & ReturnType<typeof useTabs>) {
-  const childTabs = (Array.isArray(children) ? children : [children]).filter(
-    Boolean,
-  ) as ReactElement<TabItemProps>[];
-  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}: {children: ReactNode}) {
+  return <div className="margin-top--md">{children}</div>;
 }
 
-function TabsComponent(props: Props): ReactNode {
-  const tabs = useTabs(props);
+function TabsContainer({
+  className,
+  children,
+}: {
+  className?: string;
+  children: ReactNode;
+}): ReactNode {
   return (
     <div
       className={clsx(
@@ -152,21 +126,28 @@ function TabsComponent(props: Props): ReactNode {
         '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: Props): ReactNode {
   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/src/theme-classic.d.ts

@@ -48,6 +48,7 @@ declare module '@theme/Admonition' {
     readonly icon?: ReactNode;
     readonly title?: ReactNode;
     readonly className?: string;
+    readonly id?: string;
   }
 
   export default function Admonition(props: Props): ReactNode;
@@ -123,6 +124,7 @@ declare module '@theme/Admonition/Layout' {
     readonly icon?: ReactNode;
     readonly title?: ReactNode;
     readonly className?: string;
+    readonly id?: string;
   }
   export default function AdmonitionLayout(props: Props): ReactNode;
 }
@@ -580,6 +582,71 @@ declare module '@theme/DocCard' {
   export default function DocCard(props: Props): ReactNode;
 }
 
+declare module '@theme/DocCard/Heading' {
+  import type {ReactNode} from 'react';
+  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly item: PropSidebarItem;
+    readonly icon: ReactNode;
+    readonly title: string;
+  }
+
+  export default function DocCardHeading(props: Props): ReactNode;
+}
+
+declare module '@theme/DocCard/Heading/Icon' {
+  import type {ReactNode} from 'react';
+  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly item: PropSidebarItem;
+    readonly icon: ReactNode;
+  }
+
+  export default function DocCardHeadingIcon(props: Props): ReactNode;
+}
+
+declare module '@theme/DocCard/Heading/Text' {
+  import type {ReactNode} from 'react';
+  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly item: PropSidebarItem;
+    readonly title: string;
+  }
+
+  export default function DocCardHeadingText(props: Props): ReactNode;
+}
+
+declare module '@theme/DocCard/Description' {
+  import type {ReactNode} from 'react';
+  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly item: PropSidebarItem;
+    readonly description: string;
+  }
+
+  export default function DocCardDescription(props: Props): ReactNode;
+}
+
+declare module '@theme/DocCard/Layout' {
+  import type {ReactNode} from 'react';
+  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly item: PropSidebarItem;
+    readonly className?: string;
+    readonly href: string;
+    readonly icon: ReactNode;
+    readonly title: string;
+    readonly description?: string;
+  }
+
+  export default function DocCardLayout(props: Props): ReactNode;
+}
+
 declare module '@theme/DocCardList' {
   import type {ReactNode} from 'react';
   import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
@@ -1743,11 +1810,11 @@ declare module '@theme/Icon/LightMode' {
 }
 
 declare module '@theme/Icon/SystemColorMode' {
-  import type {ComponentProps} from 'react';
+  import type {ComponentProps, ReactNode} from 'react';
 
   export interface Props extends ComponentProps<'svg'> {}
 
-  export default function IconSystemColorMode(props: Props): JSX.Element;
+  export default function IconSystemColorMode(props: Props): ReactNode;
 }
 
 declare module '@theme/Icon/Menu' {