fix(theme): Doc sidebar links/categories with long labels should display properly (#11356)

Co-authored-by: slorber <749374+slorber@users.noreply.github.com>

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category/index.tsx

@@ -31,6 +31,8 @@ import useIsBrowser from '@docusaurus/useIsBrowser';
 import DocSidebarItems from '@theme/DocSidebarItems';
 import type {Props} from '@theme/DocSidebarItem/Category';
 
+import styles from './styles.module.css';
+
 // If we navigate to a category and it becomes active, it should automatically
 // expand itself
 function useAutoExpandActiveCategory({
@@ -126,6 +128,14 @@ function CollapseButton({
   );
 }
 
+function CategoryLinkLabel({label}: {label: string}) {
+  return (
+    <span title={label} className={styles.categoryLinkLabel}>
+      {label}
+    </span>
+  );
+}
+
 export default function DocSidebarItemCategory({
   item,
   onItemClick,
@@ -179,6 +189,29 @@ export default function DocSidebarItemCategory({
     }
   }, [collapsible, expandedItem, index, setCollapsed, autoCollapseCategories]);
 
+  const handleItemClick: ComponentProps<'a'>['onClick'] = (e) => {
+    onItemClick?.(item);
+    if (collapsible) {
+      if (href) {
+        // When already on the category's page, we collapse it
+        // We don't use "isActive" because it would collapse the
+        // category even when we browse a children element
+        // See https://github.com/facebook/docusaurus/issues/11213
+        if (isCurrentPage) {
+          e.preventDefault();
+          updateCollapsed();
+        } else {
+          // When navigating to a new category, we always expand
+          // see https://github.com/facebook/docusaurus/issues/10854#issuecomment-2609616182
+          updateCollapsed(false);
+        }
+      } else {
+        e.preventDefault();
+        updateCollapsed();
+      }
+    }
+  };
+
   return (
     <li
       className={clsx(
@@ -195,43 +228,18 @@ export default function DocSidebarItemCategory({
           'menu__list-item-collapsible--active': isCurrentPage,
         })}>
         <Link
-          className={clsx('menu__link', {
+          className={clsx(styles.categoryLink, 'menu__link', {
             'menu__link--sublist': collapsible,
             'menu__link--sublist-caret': !href && collapsible,
             'menu__link--active': isActive,
           })}
-          onClick={
-            collapsible
-              ? (e) => {
-                  onItemClick?.(item);
-                  if (href) {
-                    // When already on the category's page, we collapse it
-                    // We don't use "isActive" because it would collapse the
-                    // category even when we browse a children element
-                    // See https://github.com/facebook/docusaurus/issues/11213
-                    if (isCurrentPage) {
-                      e.preventDefault();
-                      updateCollapsed();
-                    } else {
-                      // When navigating to a new category, we always expand
-                      // see https://github.com/facebook/docusaurus/issues/10854#issuecomment-2609616182
-                      updateCollapsed(false);
-                    }
-                  } else {
-                    e.preventDefault();
-                    updateCollapsed();
-                  }
-                }
-              : () => {
-                  onItemClick?.(item);
-                }
-          }
+          onClick={handleItemClick}
           aria-current={isCurrentPage ? 'page' : undefined}
           role={collapsible && !href ? 'button' : undefined}
           aria-expanded={collapsible && !href ? !collapsed : undefined}
           href={collapsible ? hrefWithSSRFallback ?? '#' : hrefWithSSRFallback}
           {...props}>
-          {label}
+          <CategoryLinkLabel label={label} />
         </Link>
         {href && collapsible && (
           <CollapseButton

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category/styles.module.css

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+
+.categoryLink {
+  overflow: hidden;
+}
+
+/*
+TODO merge this logic back in Infima?
+ */
+:global(.menu__link--sublist-caret)::after {
+  margin-left: var(--ifm-menu-link-padding-vertical);
+}
+
+.categoryLinkLabel {
+  flex: 1;
+  overflow: hidden;
+  display: -webkit-box;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Link/index.tsx

@@ -16,6 +16,14 @@ import type {Props} from '@theme/DocSidebarItem/Link';
 
 import styles from './styles.module.css';
 
+function LinkLabel({label}: {label: string}) {
+  return (
+    <span title={label} className={styles.linkLabel}>
+      {label}
+    </span>
+  );
+}
+
 export default function DocSidebarItemLink({
   item,
   onItemClick,
@@ -51,7 +59,7 @@ export default function DocSidebarItemLink({
           onClick: onItemClick ? () => onItemClick(item) : undefined,
         })}
         {...props}>
-        {label}
+        <LinkLabel label={label} />
         {!isInternalLink && <IconExternalLink />}
       </Link>
     </li>

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Link/styles.module.css

@@ -8,3 +8,11 @@
 .menuExternalLink {
   align-items: center;
 }
+
+.linkLabel {
+  overflow: hidden;
+  display: -webkit-box;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}

project-words.txt

@@ -136,6 +136,7 @@ lifecycles
 lightningcss
 Linkify
 linkify
+longlonglonglonglonglonglonglonglonglonglonglong
 Lorber
 lorber
 Lorber's

website/_dogfooding/_docs tests/tests/sidebar-display/Category 2 Long Long Long Long Long Long Long Long Long Long Long/doc1.mdx

@@ -0,0 +1 @@
+# Doc 1

website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc1.mdx

@@ -0,0 +1 @@
+# Doc 1

website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc2 long long long long long long long long long long long long.mdx

@@ -0,0 +1 @@
+# Doc 2 long long long long long long long long long long long long

website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc3longlonglonglonglonglonglonglonglonglonglonglong.mdx

@@ -0,0 +1 @@
+# Doc 3 longlonglonglonglonglonglonglonglonglonglonglong

website/_dogfooding/_docs tests/tests/sidebar-display/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Sidebar Display",
+  "link": {
+    "type": "generated-index",
+    "title": "Sidebar Display",
+    "description": "Testing edge cases of how the docs sidebar is displayed"
+  },
+  "position": 1
+}