docs: add prepare script to generate sidebar (#11894)

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

@@ -1,27 +1,30 @@
 "use client"
 
-import type { Area } from "@/types/openapi"
-import { capitalize, usePrevious, useSearch } from "docs-ui"
+import type { OpenAPI } from "types"
+import { capitalize, usePrevious, useSearch, useSidebar } from "docs-ui"
 import { createContext, useContext, useEffect, useMemo, useState } from "react"
+import { usePathname } from "next/navigation"
 
 type AreaContextType = {
-  area: Area
-  prevArea: Area | undefined
+  area: OpenAPI.Area
+  prevArea: OpenAPI.Area | undefined
   displayedArea: string
-  setArea: (value: Area) => void
+  setArea: (value: OpenAPI.Area) => void
 }
 
 const AreaContext = createContext<AreaContextType | null>(null)
 
 type AreaProviderProps = {
-  area: Area
+  area: OpenAPI.Area
   children: React.ReactNode
 }
 
 const AreaProvider = ({ area: passedArea, children }: AreaProviderProps) => {
-  const [area, setArea] = useState<Area>(passedArea)
+  const [area, setArea] = useState<OpenAPI.Area>(passedArea)
   const prevArea = usePrevious(area)
   const { defaultFilters, setDefaultFilters } = useSearch()
+  const { setActivePath } = useSidebar()
+  const pathname = usePathname()
 
   const displayedArea = useMemo(() => {
     return capitalize(area)
@@ -33,6 +36,10 @@ const AreaProvider = ({ area: passedArea, children }: AreaProviderProps) => {
     }
   }, [area, defaultFilters, setDefaultFilters])
 
+  useEffect(() => {
+    setActivePath(null)
+  }, [pathname])
+
   return (
     <AreaContext.Provider
       value={{

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

@@ -1,33 +1,35 @@
 "use client"
 
-import { ExpandedDocument, SecuritySchemeObject } from "@/types/openapi"
+import { OpenAPI } from "types"
 import { ReactNode, createContext, useContext, useEffect, useMemo } from "react"
 import { Sidebar } 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"
+import { UpdateActionType, UpdateSidebarItemTypes, useSidebar } from "docs-ui"
+import { getSectionId } from "docs-utils"
 
 type BaseSpecsContextType = {
-  baseSpecs: ExpandedDocument | undefined
-  getSecuritySchema: (securityName: string) => SecuritySchemeObject | null
+  baseSpecs: OpenAPI.ExpandedDocument | undefined
+  getSecuritySchema: (
+    securityName: string
+  ) => OpenAPI.SecuritySchemeObject | null
 }
 
 const BaseSpecsContext = createContext<BaseSpecsContextType | null>(null)
 
 type BaseSpecsProviderProps = {
-  baseSpecs: ExpandedDocument | undefined
+  baseSpecs: OpenAPI.ExpandedDocument | undefined
   children?: ReactNode
 }
 
 const BaseSpecsProvider = ({ children, baseSpecs }: BaseSpecsProviderProps) => {
   const router = useRouter()
-  const { activePath, addItems, setActivePath, resetItems, shownSidebar } =
+  const { activePath, setActivePath, resetItems, shownSidebar, updateItems } =
     useSidebar()
 
   const getSecuritySchema = (
     securityName: string
-  ): SecuritySchemeObject | null => {
+  ): OpenAPI.SecuritySchemeObject | null => {
     if (
       baseSpecs?.components?.securitySchemes &&
       Object.prototype.hasOwnProperty.call(
@@ -44,16 +46,12 @@ const BaseSpecsProvider = ({ children, baseSpecs }: BaseSpecsProviderProps) => {
     return null
   }
 
-  const itemsToAdd = useMemo(() => {
+  const itemsToUpdate = useMemo(() => {
     if (!baseSpecs) {
       return []
     }
 
-    const itemsToAdd: Sidebar.SidebarItem[] = [
-      {
-        type: "separator",
-      },
-    ]
+    const itemsToUpdate: UpdateActionType["items"] = []
 
     baseSpecs.tags?.forEach((tag) => {
       const tagPathName = getSectionId([tag.name.toLowerCase()])
@@ -62,37 +60,44 @@ const BaseSpecsProvider = ({ children, baseSpecs }: BaseSpecsProviderProps) => {
         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: () => {
-          if (location.hash !== tagPathName) {
-            router.push(`#${tagPathName}`, {
-              scroll: false,
-            })
-          }
-          if (activePath !== tagPathName) {
-            setActivePath(tagPathName)
-          }
+      itemsToUpdate.push({
+        existingItem: {
+          type: "category",
+          title: tag.name,
+        },
+        newItem: {
+          children: childItems,
+          loaded: childItems.length > 0,
+          onOpen: () => {
+            if (location.hash !== tagPathName) {
+              router.push(`#${tagPathName}`, {
+                scroll: false,
+              })
+            }
+            if (activePath !== tagPathName) {
+              setActivePath(tagPathName)
+            }
+          },
+        },
+        options: {
+          setChildrenBehavior: "merge",
         },
       })
     })
 
-    return itemsToAdd
+    return itemsToUpdate
   }, [baseSpecs])
 
   useEffect(() => {
-    if (!itemsToAdd.length || !shownSidebar) {
+    if (!itemsToUpdate.length || !shownSidebar) {
       return
     }
 
-    addItems(itemsToAdd, {
+    updateItems({
       sidebar_id: shownSidebar.sidebar_id,
+      items: itemsToUpdate,
     })
-  }, [itemsToAdd, shownSidebar?.sidebar_id])
+  }, [itemsToUpdate, shownSidebar?.sidebar_id])
 
   useEffect(() => {
     return () => {

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

@@ -5,6 +5,9 @@ import {
   usePageLoading,
   useScrollController,
 } from "docs-ui"
+import { usePathname } from "next/navigation"
+import { Sidebar } from "types"
+import { useCallback, useEffect, useState } from "react"
 import { config } from "../config"
 
 type SidebarProviderProps = {
@@ -14,6 +17,26 @@ type SidebarProviderProps = {
 const SidebarProvider = ({ children }: SidebarProviderProps) => {
   const { isLoading, setIsLoading } = usePageLoading()
   const { scrollableElement } = useScrollController()
+  const [sidebar, setSidebar] = useState<Sidebar.Sidebar | undefined>()
+  const path = usePathname()
+
+  const loadSidebar = useCallback(async () => {
+    if (path.startsWith("/store")) {
+      return (await import("../generated/generated-store-sidebar.mjs"))
+        .default as Sidebar.Sidebar
+    }
+
+    return (await import("../generated/generated-admin-sidebar.mjs"))
+      .default as Sidebar.Sidebar
+  }, [path])
+
+  useEffect(() => {
+    loadSidebar()
+      .then(setSidebar)
+      .catch((error) => {
+        console.error("Error loading sidebar:", error)
+      })
+  }, [loadSidebar])
 
   return (
     <UiSidebarProvider
@@ -22,7 +45,7 @@ const SidebarProvider = ({ children }: SidebarProviderProps) => {
       shouldHandleHashChange={true}
       shouldHandlePathChange={false}
       scrollableElement={scrollableElement}
-      sidebars={config.sidebars}
+      sidebars={sidebar ? [sidebar] : config.sidebars}
       persistCategoryState={false}
       disableActiveTransition={false}
       isSidebarStatic={false}