docs: fixes and refactoring for API reference (#9708)

* docs: fixes and refactoring for API reference

* add route caching

* remove caching

* use next cache

www/apps/api-reference/providers/base-specs.tsx

@@ -1,28 +1,34 @@
 "use client"
 
 import { ExpandedDocument, SecuritySchemeObject } from "@/types/openapi"
-import { ReactNode, createContext, useContext, useState } from "react"
+import {
+  ReactNode,
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+} from "react"
+import { SidebarItem, SidebarItemSections } from "types"
+import getSectionId from "../utils/get-section-id"
+import getTagChildSidebarItems from "../utils/get-tag-child-sidebar-items"
+import { useRouter } from "next/navigation"
+import { useSidebar } from "docs-ui"
 
 type BaseSpecsContextType = {
-  baseSpecs: ExpandedDocument | null
-  setBaseSpecs: React.Dispatch<React.SetStateAction<ExpandedDocument | null>>
+  baseSpecs: ExpandedDocument | undefined
   getSecuritySchema: (securityName: string) => SecuritySchemeObject | null
 }
 
 const BaseSpecsContext = createContext<BaseSpecsContextType | null>(null)
 
 type BaseSpecsProviderProps = {
-  initialSpecs?: ExpandedDocument | null
+  baseSpecs: ExpandedDocument | undefined
   children?: ReactNode
 }
 
-const BaseSpecsProvider = ({
-  children,
-  initialSpecs = null,
-}: BaseSpecsProviderProps) => {
-  const [baseSpecs, setBaseSpecs] = useState<ExpandedDocument | null>(
-    initialSpecs
-  )
+const BaseSpecsProvider = ({ children, baseSpecs }: BaseSpecsProviderProps) => {
+  const router = useRouter()
+  const { activePath, addItems, setActivePath, resetItems } = useSidebar()
 
   const getSecuritySchema = (
     securityName: string
@@ -43,11 +49,63 @@ const BaseSpecsProvider = ({
     return null
   }
 
+  const handleOpen = useCallback(
+    (tagPathName: string) => {
+      if (location.hash !== tagPathName) {
+        router.push(`#${tagPathName}`, {
+          scroll: false,
+        })
+      }
+      if (activePath !== tagPathName) {
+        setActivePath(tagPathName)
+      }
+    },
+    [activePath, router, setActivePath]
+  )
+
+  useEffect(() => {
+    if (!baseSpecs) {
+      return
+    }
+
+    const itemsToAdd: SidebarItem[] = [
+      {
+        type: "separator",
+      },
+    ]
+
+    baseSpecs.tags?.forEach((tag) => {
+      const tagPathName = getSectionId([tag.name.toLowerCase()])
+      const childItems =
+        baseSpecs.expandedTags &&
+        Object.hasOwn(baseSpecs.expandedTags, tagPathName)
+          ? getTagChildSidebarItems(baseSpecs.expandedTags[tagPathName])
+          : []
+      itemsToAdd.push({
+        type: "category",
+        title: tag.name,
+        children: childItems,
+        loaded: childItems.length > 0,
+        showLoadingIfEmpty: true,
+        onOpen: () => {
+          handleOpen(tagPathName)
+        },
+      })
+    })
+
+    addItems(itemsToAdd, {
+      section: SidebarItemSections.DEFAULT,
+    })
+
+    return () => {
+      resetItems()
+    }
+  }, [baseSpecs])
+
   return (
     <BaseSpecsContext.Provider
       value={{
         baseSpecs,
-        setBaseSpecs,
         getSecuritySchema,
       }}
     >

www/apps/api-reference/providers/index.tsx

@@ -1,12 +1,9 @@
-"use client"
-
 import {
   AnalyticsProvider,
   PageLoadingProvider,
   ScrollControllerProvider,
   SiteConfigProvider,
 } from "docs-ui"
-import BaseSpecsProvider from "./base-specs"
 import SidebarProvider from "./sidebar"
 import SearchProvider from "./search"
 import { config } from "../config"
@@ -21,15 +18,13 @@ const Providers = ({ children }: ProvidersProps) => {
     <AnalyticsProvider writeKey={process.env.NEXT_PUBLIC_SEGMENT_API_KEY}>
       <SiteConfigProvider config={config}>
         <PageLoadingProvider>
-          <BaseSpecsProvider>
-            <ScrollControllerProvider scrollableSelector="#main">
-              <SidebarProvider>
-                <MainNavProvider>
-                  <SearchProvider>{children}</SearchProvider>
-                </MainNavProvider>
-              </SidebarProvider>
-            </ScrollControllerProvider>
-          </BaseSpecsProvider>
+          <ScrollControllerProvider scrollableSelector="#main">
+            <SidebarProvider>
+              <MainNavProvider>
+                <SearchProvider>{children}</SearchProvider>
+              </MainNavProvider>
+            </SidebarProvider>
+          </ScrollControllerProvider>
         </PageLoadingProvider>
       </SiteConfigProvider>
     </AnalyticsProvider>

www/apps/api-reference/providers/sidebar.tsx

@@ -3,12 +3,9 @@
 import {
   SidebarProvider as UiSidebarProvider,
   usePageLoading,
-  usePrevious,
   useScrollController,
 } from "docs-ui"
 import { config } from "../config"
-import { useCallback } from "react"
-import { usePathname } from "next/navigation"
 
 type SidebarProviderProps = {
   children?: React.ReactNode
@@ -17,13 +14,6 @@ type SidebarProviderProps = {
 const SidebarProvider = ({ children }: SidebarProviderProps) => {
   const { isLoading, setIsLoading } = usePageLoading()
   const { scrollableElement } = useScrollController()
-  const pathname = usePathname()
-  const prevPathName = usePrevious(pathname)
-
-  const resetOnCondition = useCallback(
-    () => prevPathName !== undefined && pathname !== prevPathName,
-    [pathname, prevPathName]
-  )
 
   return (
     <UiSidebarProvider
@@ -32,7 +22,6 @@ const SidebarProvider = ({ children }: SidebarProviderProps) => {
       shouldHandleHashChange={true}
       scrollableElement={scrollableElement}
       initialItems={config.sidebar}
-      resetOnCondition={resetOnCondition}
       persistState={false}
       projectName="api"
     >