feat(theme): Split <DocCard>, improve extensibility, better handling of emoji icons, stable classNames

packages/docusaurus-theme-classic/src/theme-classic.d.ts

@@ -582,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';

packages/docusaurus-theme-classic/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>
+  );
+}

packages/docusaurus-theme-classic/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;
+}

packages/docusaurus-theme-classic/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>
+  );
+}

packages/docusaurus-theme-classic/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;
+}

packages/docusaurus-theme-classic/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>
+  );
+}

packages/docusaurus-theme-classic/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;
+}

packages/docusaurus-theme-classic/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>
+  );
+}

packages/docusaurus-theme-classic/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;
+}

packages/docusaurus-theme-classic/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>
+  );
+}

packages/docusaurus-theme-classic/src/theme/DocCard/styles.module.css → packages/docusaurus-theme-classic/src/theme/DocCard/Layout/styles.module.css

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