docs: redesign sidebar

www/apps/api-reference/app/admin/page.tsx

@@ -15,7 +15,7 @@ const ReferencePage = async () => {
         </h1>
         <DividedLayout
           mainContent={
-            <Section>
+            <Section checkActiveOnScroll={true}>
               <h1 className="!text-h2 hidden lg:block">
                 Medusa V2 Admin API Reference
               </h1>

www/apps/api-reference/app/layout.tsx

@@ -1,5 +1,4 @@
 import "./globals.css"
-import Navbar from "@/components/Navbar"
 import Providers from "../providers"
 import { WideLayout } from "docs-ui"
 import { Inter, Roboto_Mono } from "next/font/google"
@@ -29,8 +28,12 @@ export default function RootLayout({
   return (
     <WideLayout
       ProvidersComponent={Providers}
-      NavbarComponent={Navbar}
+      sidebarProps={{
+        expandItems: false,
+      }}
       bodyClassName={clsx(inter.variable, robotoMono.variable)}
+      showToc={false}
+      showBanner={false}
     >
       {children}
     </WideLayout>

www/apps/api-reference/app/store/page.tsx

@@ -15,7 +15,7 @@ const ReferencePage = async () => {
         </h1>
         <DividedLayout
           mainContent={
-            <Section>
+            <Section checkActiveOnScroll={true}>
               <h1 className="!text-h2 hidden lg:block">
                 Medusa V2 Store API Reference
               </h1>

www/apps/api-reference/components/MDXComponents/H2/index.tsx

@@ -1,73 +1,47 @@
 "use client"
 
-import { InView } from "react-intersection-observer"
-import { isElmWindow, useScrollController, useSidebar } from "docs-ui"
-import checkElementInViewport from "../../../utils/check-element-in-viewport"
-import { useEffect, useMemo } from "react"
+import { useScrollController, useSidebar } from "docs-ui"
+import { useEffect, useMemo, useRef, useState } from "react"
 import getSectionId from "../../../utils/get-section-id"
 
-type H2Props = {
-  addToSidebar?: boolean
-} & React.HTMLAttributes<HTMLHeadingElement>
+type H2Props = React.HTMLAttributes<HTMLHeadingElement>
 
-const H2 = ({ addToSidebar = true, children, ...props }: H2Props) => {
-  const { activePath, setActivePath, addItems } = useSidebar()
-  const { getScrolledTop, scrollableElement } = useScrollController()
+const H2 = ({ children, ...props }: H2Props) => {
+  const headingRef = useRef<HTMLHeadingElement>(null)
+  const { activePath, addItems } = useSidebar()
+  const { scrollableElement, scrollToElement } = useScrollController()
+  const [scrolledFirstTime, setScrolledFirstTime] = useState(false)
 
-  const handleViewChange = (
-    inView: boolean,
-    entry: IntersectionObserverEntry
-  ) => {
-    if (!addToSidebar) {
+  const id = useMemo(() => getSectionId([children as string]), [children])
+
+  useEffect(() => {
+    if (!scrollableElement || !headingRef.current || scrolledFirstTime) {
       return
     }
-    const heading = entry.target
-    if (
-      (inView ||
-        checkElementInViewport(heading.parentElement || heading, 40)) &&
-      getScrolledTop() !== 0 &&
-      activePath !== heading.id
-    ) {
-      // can't use next router as it doesn't support
-      // changing url without scrolling
-      history.pushState({}, "", `#${heading.id}`)
-      setActivePath(heading.id)
-    }
-  }
-  const id = getSectionId([children as string])
 
-  useEffect(() => {
     if (id === (activePath || location.hash.replace("#", ""))) {
-      const elm = document.getElementById(id)
-      elm?.scrollIntoView()
+      scrollToElement(
+        (headingRef.current.offsetParent as HTMLElement) || headingRef.current
+      )
     }
+    setScrolledFirstTime(scrolledFirstTime)
+  }, [scrollableElement, headingRef, id])
 
+  useEffect(() => {
     addItems([
       {
+        type: "link",
         path: `${id}`,
         title: children as string,
         loaded: true,
       },
     ])
-  }, [])
-
-  const root = useMemo(() => {
-    return isElmWindow(scrollableElement) ? document.body : scrollableElement
-  }, [scrollableElement])
+  }, [id])
 
   return (
-    <InView
-      as="h2"
-      threshold={0.4}
-      skip={!addToSidebar}
-      initialInView={false}
-      {...props}
-      onChange={handleViewChange}
-      id={id}
-      root={root}
-    >
+    <h2 {...props} id={id} ref={headingRef}>
       {children}
-    </InView>
+    </h2>
   )
 }
 

www/apps/api-reference/components/MDXComponents/index.tsx

@@ -14,9 +14,7 @@ const getCustomComponents = (scope?: ScopeType): MDXComponents => {
     ...UiMDXComponents,
     Security: () => <Security specs={scope?.specs} />,
     a: Link,
-    h2: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
-      <H2 addToSidebar={scope?.addToSidebar} {...props} />
-    ),
+    h2: (props: React.HTMLAttributes<HTMLHeadingElement>) => <H2 {...props} />,
   }
 }
 

www/apps/api-reference/components/Section/index.tsx

@@ -1,14 +1,25 @@
 "use client"
 
 import clsx from "clsx"
+import { useActiveOnScroll, useSidebar } from "docs-ui"
 import { useEffect, useRef } from "react"
 
 export type SectionProps = {
-  addToSidebar?: boolean
+  checkActiveOnScroll?: boolean
 } & React.AllHTMLAttributes<HTMLDivElement>
 
-const Section = ({ children, className }: SectionProps) => {
+const Section = ({
+  children,
+  className,
+  checkActiveOnScroll = false,
+}: SectionProps) => {
   const sectionRef = useRef<HTMLDivElement>(null)
+  const { activeItemId } = useActiveOnScroll({
+    rootElm: sectionRef.current || undefined,
+    enable: checkActiveOnScroll,
+    useDefaultIfNoActive: false,
+  })
+  const { setActivePath } = useSidebar()
 
   useEffect(() => {
     if ("scrollRestoration" in history) {
@@ -17,6 +28,13 @@ const Section = ({ children, className }: SectionProps) => {
     }
   }, [])
 
+  useEffect(() => {
+    if (activeItemId.length) {
+      history.pushState({}, "", `#${activeItemId}`)
+      setActivePath(activeItemId)
+    }
+  }, [activeItemId])
+
   return (
     <div
       ref={sectionRef}

www/apps/api-reference/components/Tags/Operation/index.tsx

@@ -13,6 +13,7 @@ import TagsOperationDescriptionSection from "./DescriptionSection"
 import DividedLayout from "@/layouts/Divided"
 import { useLoading } from "@/providers/loading"
 import SectionDivider from "../../Section/Divider"
+import checkElementInViewport from "../../../utils/check-element-in-viewport"
 
 const TagOperationCodeSection = dynamic<TagOperationCodeSectionProps>(
   async () => import("./CodeSection")
@@ -40,7 +41,7 @@ const TagOperation = ({
   )
   const nodeRef = useRef<Element | null>(null)
   const { loading, removeLoading } = useLoading()
-  const { scrollableElement } = useScrollController()
+  const { scrollableElement, scrollToTop } = useScrollController()
   const root = useMemo(() => {
     return isElmWindow(scrollableElement) ? document.body : scrollableElement
   }, [scrollableElement])
@@ -75,24 +76,28 @@ const TagOperation = ({
     [ref]
   )
 
-  useEffect(() => {
-    const enableShow = () => {
-      setShow(true)
+  const scrollIntoView = useCallback(() => {
+    if (nodeRef.current && !checkElementInViewport(nodeRef.current, 10)) {
+      const elm = nodeRef.current as HTMLElement
+      scrollToTop(
+        elm.offsetTop + (elm.offsetParent as HTMLElement)?.offsetTop,
+        0
+      )
     }
+    setShow(true)
+  }, [scrollToTop, nodeRef])
 
+  useEffect(() => {
     if (nodeRef && nodeRef.current) {
       removeLoading()
       const currentHash = location.hash.replace("#", "")
       if (currentHash === path) {
-        setTimeout(() => {
-          nodeRef.current?.scrollIntoView()
-          enableShow()
-        }, 100)
+        setTimeout(scrollIntoView, 100)
       } else if (currentHash.split("_")[0] === path.split("_")[0]) {
-        enableShow()
+        setShow(true)
       }
     }
-  }, [nodeRef, path])
+  }, [nodeRef, path, scrollIntoView])
 
   return (
     <div

www/apps/api-reference/components/Tags/Paths/index.tsx

@@ -14,7 +14,7 @@ import { useBaseSpecs } from "@/providers/base-specs"
 import getTagChildSidebarItems from "@/utils/get-tag-child-sidebar-items"
 import { useLoading } from "@/providers/loading"
 import DividedLoading from "@/components/DividedLoading"
-import { SidebarItemSections, SidebarItemType } from "types"
+import { SidebarItemSections, SidebarItem, SidebarItemCategory } from "types"
 import basePathUrl from "../../../utils/base-path-url"
 
 const TagOperation = dynamic<TagOperationProps>(
@@ -56,16 +56,17 @@ const TagPaths = ({ tag, className }: TagPathsProps) => {
   useEffect(() => {
     if (paths) {
       const parentItem = findItemInSection(
-        items[SidebarItemSections.BOTTOM],
-        { path: tagSlugName },
+        items[SidebarItemSections.DEFAULT],
+        { title: tag.name },
         false
-      )
-      const pathItems: SidebarItemType[] = getTagChildSidebarItems(paths)
+      ) as SidebarItemCategory
+      const pathItems: SidebarItem[] = getTagChildSidebarItems(paths)
       if ((parentItem?.children?.length || 0) < pathItems.length) {
         addItems(pathItems, {
-          section: SidebarItemSections.BOTTOM,
+          section: SidebarItemSections.DEFAULT,
           parent: {
-            path: tagSlugName,
+            title: tag.name,
+            path: "",
             changeLoaded: true,
           },
         })