From 924f6e96929138b7b6cdf3a498b9a79ed9befdf8 Mon Sep 17 00:00:00 2001
From: Charles Zhao <charleszhao@silverhand.io>
Date: Tue, 10 Dec 2024 14:29:08 +0800
Subject: [PATCH] feat: add sublist label support in sidebar items

---
 .../account-settings/README.mdx               |   2 +
 .../organization-experience/README.mdx        |   2 +
 .../sign-up-and-sign-in/README.mdx            |   2 +
 src/scss/custom.scss                          |   2 +-
 .../DocSidebarItem/Category/index.module.scss |  20 +++
 src/theme/DocSidebarItem/Category/index.tsx   | 146 ++++++++++--------
 6 files changed, 105 insertions(+), 69 deletions(-)

diff --git a/docs/end-user-flows/account-settings/README.mdx b/docs/end-user-flows/account-settings/README.mdx
index 02312d6206f..6f713a79e7e 100644
--- a/docs/end-user-flows/account-settings/README.mdx
+++ b/docs/end-user-flows/account-settings/README.mdx
@@ -1,5 +1,7 @@
 ---
 sidebar_position: 7
+sidebar_custom_props:
+  sublist_label: Account flows
 ---
 
 import GearIcon from '@site/src/assets/gear.svg';
diff --git a/docs/end-user-flows/organization-experience/README.mdx b/docs/end-user-flows/organization-experience/README.mdx
index 9792326aaef..e67e6552091 100644
--- a/docs/end-user-flows/organization-experience/README.mdx
+++ b/docs/end-user-flows/organization-experience/README.mdx
@@ -1,5 +1,7 @@
 ---
 sidebar_position: 9
+sidebar_custom_props:
+  sublist_label: Organization flows
 ---
 
 import GearIcon from '@site/src/assets/gear.svg';
diff --git a/docs/end-user-flows/sign-up-and-sign-in/README.mdx b/docs/end-user-flows/sign-up-and-sign-in/README.mdx
index abed7285ff4..4a870bcd6c2 100644
--- a/docs/end-user-flows/sign-up-and-sign-in/README.mdx
+++ b/docs/end-user-flows/sign-up-and-sign-in/README.mdx
@@ -1,5 +1,7 @@
 ---
 sidebar_position: 1
+sidebar_custom_props:
+  sublist_label: Authentication flows
 ---
 
 # Sign-up and sign-in
diff --git a/src/scss/custom.scss b/src/scss/custom.scss
index 26273d75d14..663a5eb57d2 100644
--- a/src/scss/custom.scss
+++ b/src/scss/custom.scss
@@ -597,7 +597,7 @@ aside + main {
   }
 
   .theme-doc-sidebar-container nav {
-    padding: var(--ifm-navbar-padding-horizontal) _.unit(3);
+    padding: var(--ifm-navbar-padding-horizontal) _.unit(2);
   }
 }
 
diff --git a/src/theme/DocSidebarItem/Category/index.module.scss b/src/theme/DocSidebarItem/Category/index.module.scss
index 25bafeb6961..fd76f3a1ae0 100644
--- a/src/theme/DocSidebarItem/Category/index.module.scss
+++ b/src/theme/DocSidebarItem/Category/index.module.scss
@@ -1,3 +1,23 @@
 .icon {
   margin-inline-end: 12px;
 }
+
+.sublistLabel {
+  display: flex;
+  align-items: center;
+  font-size: 12px;
+  font-weight: 700;
+  line-height: 16px;
+  color: var(--logto-color-placeholder);
+  text-transform: capitalize;
+  padding: 8px 26px;
+  position: relative;
+  gap: 8px;
+  user-select: none;
+
+  .divider {
+    flex: 1;
+    height: 0;
+    border-top: 1px solid var(--logto-line-divider);
+  }
+}
diff --git a/src/theme/DocSidebarItem/Category/index.tsx b/src/theme/DocSidebarItem/Category/index.tsx
index 73b29480c04..4c712157a68 100644
--- a/src/theme/DocSidebarItem/Category/index.tsx
+++ b/src/theme/DocSidebarItem/Category/index.tsx
@@ -14,6 +14,7 @@ import {
 } from '@docusaurus/theme-common';
 import { isSamePath } from '@docusaurus/theme-common/internal';
 import useIsBrowser from '@docusaurus/useIsBrowser';
+import { cond, condString } from '@silverhand/essentials';
 import type { Props } from '@theme/DocSidebarItem/Category';
 import DocSidebarItems from '@theme/DocSidebarItems';
 import clsx from 'clsx';
@@ -112,7 +113,8 @@ export default function DocSidebarItemCategory({
   ...props
 }: Props): JSX.Element {
   const { items, label, collapsible, className, href, customProps } = item;
-  const Icon = typeof customProps?.id === 'string' ? icons[customProps.id] : undefined;
+  const Icon = cond(typeof customProps?.id === 'string' && icons[customProps.id]);
+  const sublistLabel = condString(customProps?.sublist_label);
   const {
     docs: {
       sidebar: { autoCollapseCategories },
@@ -148,77 +150,85 @@ export default function DocSidebarItemCategory({
   }, [collapsible, expandedItem, index, setCollapsed, autoCollapseCategories]);
 
   return (
-    <li
-      className={clsx(
-        ThemeClassNames.docs.docSidebarItemCategory,
-        ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
-        'menu__list-item',
-        {
-          'menu__list-item--collapsed': collapsed,
-        },
-        className
+    <>
+      {sublistLabel && (
+        <li className={clsx('menu__list-item', styles.sublistLabel)}>
+          <span>{sublistLabel}</span>
+          <div className={styles.divider} />
+        </li>
       )}
-    >
-      <div
-        className={clsx('menu__list-item-collapsible', {
-          'menu__list-item-collapsible--active': isCurrentPage,
-        })}
+      <li
+        className={clsx(
+          ThemeClassNames.docs.docSidebarItemCategory,
+          ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
+          'menu__list-item',
+          {
+            'menu__list-item--collapsed': collapsed,
+          },
+          className
+        )}
       >
-        <Link
-          className={clsx('menu__link', {
-            'menu__link--sublist': collapsible,
-            // @charles modified this:
-            // 'menu__link--sublist-caret': !href && collapsible,
-            'menu__link--active': isActive,
+        <div
+          className={clsx('menu__list-item-collapsible', {
+            'menu__list-item-collapsible--active': isCurrentPage,
           })}
-          aria-current={isCurrentPage ? 'page' : undefined}
-          role={collapsible && !href ? 'button' : undefined}
-          aria-expanded={collapsible && !href ? !collapsed : undefined}
-          href={collapsible ? (hrefWithSSRFallback ?? '#') : hrefWithSSRFallback}
-          onClick={
-            collapsible
-              ? (event) => {
-                  onItemClick?.(item);
-                  if (href) {
-                    updateCollapsed(false);
-                  } else {
-                    event.preventDefault();
-                    updateCollapsed();
-                  }
-                }
-              : () => {
-                  onItemClick?.(item);
-                }
-          }
-          {...props}
         >
-          {/** @charles added category icon support */}
-          {Icon && <Icon className={styles.icon} />}
-          {label}
-        </Link>
-        {/* @charles modified this: */}
-        {/* {href && collapsible && ( */}
-        {collapsible && (
-          <CollapseButton
-            collapsed={collapsed}
-            categoryLabel={label}
-            onClick={(event) => {
-              event.preventDefault();
-              updateCollapsed();
-            }}
-          />
-        )}
-      </div>
+          <Link
+            className={clsx('menu__link', {
+              'menu__link--sublist': collapsible,
+              // @charles modified this:
+              // 'menu__link--sublist-caret': !href && collapsible,
+              'menu__link--active': isActive,
+            })}
+            aria-current={isCurrentPage ? 'page' : undefined}
+            role={collapsible && !href ? 'button' : undefined}
+            aria-expanded={collapsible && !href ? !collapsed : undefined}
+            href={collapsible ? (hrefWithSSRFallback ?? '#') : hrefWithSSRFallback}
+            onClick={
+              collapsible
+                ? (event) => {
+                    onItemClick?.(item);
+                    if (href) {
+                      updateCollapsed(false);
+                    } else {
+                      event.preventDefault();
+                      updateCollapsed();
+                    }
+                  }
+                : () => {
+                    onItemClick?.(item);
+                  }
+            }
+            {...props}
+          >
+            {/** @charles added category icon support */}
+            {Icon && <Icon className={styles.icon} />}
+            {label}
+          </Link>
+          {/* @charles modified this: */}
+          {/* {href && collapsible && ( */}
+          {collapsible && (
+            <CollapseButton
+              collapsed={collapsed}
+              categoryLabel={label}
+              onClick={(event) => {
+                event.preventDefault();
+                updateCollapsed();
+              }}
+            />
+          )}
+        </div>
 
-      <Collapsible lazy as="ul" className="menu__list" collapsed={collapsed}>
-        <DocSidebarItems
-          items={items.filter((item) => 'href' in item && item.href !== href)}
-          tabIndex={collapsed ? -1 : 0}
-          activePath={activePath}
-          level={level + 1}
-          onItemClick={onItemClick}
-        />
-      </Collapsible>
-    </li>
+        <Collapsible lazy as="ul" className="menu__list" collapsed={collapsed}>
+          <DocSidebarItems
+            items={items.filter((item) => 'href' in item && item.href !== href)}
+            tabIndex={collapsed ? -1 : 0}
+            activePath={activePath}
+            level={level + 1}
+            onItemClick={onItemClick}
+          />
+        </Collapsible>
+      </li>
+    </>
   );
 }