Docs - Category introductory page (#3715)

* Added introductory page for sidebar categories

* removed title from sidebar configuration

* Removed console and description

* Added DocCard implementation and removed DocCardList

Author: nitzanyiz

docuilib/sidebars.js

@@ -64,6 +64,10 @@ module.exports = {
             type: 'category',
             label: componentsCategories[category],
             collapsed: true,
+            link: {
+              type: 'generated-index',
+              keywords: [category]
+            },
             items: [
               {
                 type: 'autogenerated',

docuilib/src/theme/DocCard/index.tsx

@@ -0,0 +1,54 @@
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+import {findFirstSidebarItemLink} from '@docusaurus/plugin-content-docs/client';
+
+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 CardContainer({href, children}: {href: string; children: ReactNode}): JSX.Element {
+  return (
+    <Link href={href} className={clsx('card padding--lg', styles.cardContainer)}>
+      {children}
+    </Link>
+  );
+}
+
+function CardLayout({href, title}: {href: string; title: string}): JSX.Element {
+  return (
+    <CardContainer href={href}>
+      <Heading as="h2" className={clsx('text--truncate', styles.cardTitle)} title={title}>
+        {title}
+      </Heading>
+    </CardContainer>
+  );
+}
+
+function CardCategory({item}: {item: PropSidebarItemCategory}): JSX.Element | null {
+  const href = findFirstSidebarItemLink(item);
+
+  // Unexpected: categories that don't have a link have been filtered upfront
+  if (!href) {
+    return null;
+  }
+
+  return <CardLayout href={href} title={item.label}/>;
+}
+
+function CardLink({item}: {item: PropSidebarItemLink}): JSX.Element {
+  return <CardLayout href={item.href} title={item.label}/>;
+}
+
+export default function DocCard({item}: Props): JSX.Element {
+  switch (item.type) {
+    case 'link':
+      return <CardLink item={item}/>;
+    case 'category':
+      return <CardCategory item={item}/>;
+    default:
+      throw new Error(`unknown item type ${JSON.stringify(item)}`);
+  }
+}

docuilib/src/theme/DocCard/styles.module.css

@@ -0,0 +1,27 @@
+.cardContainer {
+  --ifm-link-color: var(--ifm-color-emphasis-800);
+  --ifm-link-hover-color: var(--ifm-color-emphasis-700);
+  --ifm-link-hover-decoration: none;
+
+  box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%);
+  border: 1px solid var(--ifm-color-emphasis-200);
+  transition: all var(--ifm-transition-fast) ease;
+  transition-property: border, box-shadow;
+}
+
+.cardContainer:hover {
+  border-color: var(--ifm-color-primary);
+  box-shadow: 0 3px 6px 0 rgb(0 0 0 / 20%);
+}
+
+.cardContainer *:last-child {
+  margin-bottom: 0;
+}
+
+.cardTitle {
+  font-size: 1.2rem;
+}
+
+.cardDescription {
+  font-size: 0.8rem;
+}