docs: DX and performance improvements in API reference (#9430)

- Improve scroll behavior between active sections
- Improve lag when clicking on a sidebar item
- Refactor internal working of the `SidebarProvider` to find active items faster.
- Use Next.js's `useRouter` hook for changing the hash (since they added the option to disable scroll)
- Change `isBrowser` from a hook to a provider since it's widely used across applications.
- Other general improvements and fixes.

Closes DOCS-952

www/packages/docs-ui/src/providers/BrowserProvider/index.tsx

@@ -0,0 +1,41 @@
+"use client"
+
+import React, { useContext, useEffect, useState } from "react"
+
+type BrowserContextType = {
+  isBrowser: boolean
+}
+
+const BrowserContext = React.createContext<BrowserContextType | null>(null)
+
+type BrowserProviderProps = {
+  children: React.ReactNode
+}
+
+export const BrowserProvider = ({ children }: BrowserProviderProps) => {
+  const [isBrowser, setIsBrowser] = useState(false)
+
+  useEffect(() => {
+    setIsBrowser(typeof window !== "undefined")
+  }, [])
+
+  return (
+    <BrowserContext.Provider
+      value={{
+        isBrowser,
+      }}
+    >
+      {children}
+    </BrowserContext.Provider>
+  )
+}
+
+export const useIsBrowser = () => {
+  const context = useContext(BrowserContext)
+
+  if (!context) {
+    throw new Error("useIsBrowser must be used within a BrowserProvider")
+  }
+
+  return context
+}

www/packages/docs-ui/src/providers/LearningPath/index.tsx

@@ -1,10 +1,9 @@
 "use client"
 
-import { useIsBrowser } from "@/hooks"
 import { getLearningPath } from "@/utils/learning-paths"
 import React, { createContext, useContext, useEffect, useState } from "react"
 import { LearningPathFinishType } from "@/components/LearningPath/Finish"
-import { useAnalytics } from "docs-ui"
+import { useAnalytics, useIsBrowser } from "docs-ui"
 import { usePathname, useRouter } from "next/navigation"
 
 export type LearningPathType = {
@@ -54,7 +53,7 @@ export const LearningPathProvider: React.FC<LearningPathProviderProps> = ({
 }) => {
   const [path, setPath] = useState<LearningPathType | null>(null)
   const [currentStep, setCurrentStep] = useState(-1)
-  const isBrowser = useIsBrowser()
+  const { isBrowser } = useIsBrowser()
   const pathname = usePathname()
   const router = useRouter()
   const { track } = useAnalytics()

www/packages/docs-ui/src/providers/Sidebar/index.tsx

@@ -6,13 +6,13 @@ import React, {
   useCallback,
   useContext,
   useEffect,
+  useMemo,
   useReducer,
   useRef,
   useState,
 } from "react"
 import { usePathname, useRouter } from "next/navigation"
 import { getScrolledTop } from "@/utils"
-import { useIsBrowser } from "@/hooks"
 import {
   SidebarItemSections,
   SidebarItem,
@@ -22,6 +22,7 @@ import {
   SidebarItemCategory,
   SidebarItemLinkWithParent,
 } from "types"
+import { useIsBrowser } from "../BrowserProvider"
 
 export type CurrentItemsState = SidebarSectionItems & {
   previousSidebar?: CurrentItemsState
@@ -35,7 +36,7 @@ export type SidebarContextType = {
   items: SidebarSectionItems
   currentItems: CurrentItemsState | undefined
   activePath: string | null
-  getActiveItem: () => SidebarItemLinkWithParent | undefined
+  activeItem: SidebarItemLinkWithParent | undefined
   setActivePath: (path: string | null) => void
   isLinkActive: (item: SidebarItem, checkChildren?: boolean) => boolean
   isChildrenActive: (item: SidebarItemCategory) => boolean
@@ -86,6 +87,8 @@ export type ActionType =
       replacementItems: SidebarSectionItems
     }
 
+type LinksMap = Map<string, SidebarItemLinkWithParent>
+
 const areItemsEqual = (itemA: SidebarItem, itemB: SidebarItem): boolean => {
   if (itemA.type === "separator" || itemB.type === "separator") {
     return false
@@ -122,6 +125,32 @@ const findItem = (
   return foundItem
 }
 
+const getLinksMap = (
+  items: SidebarItem[],
+  initMap?: LinksMap,
+  parentItem?: InteractiveSidebarItem
+): LinksMap => {
+  const map: LinksMap = initMap || new Map()
+
+  items.forEach((item) => {
+    if (item.type === "separator") {
+      return
+    }
+
+    if (item.type === "link") {
+      map.set(item.path, {
+        ...item,
+        parentItem,
+      })
+    }
+    if (item.children?.length) {
+      getLinksMap(item.children, map, item)
+    }
+  })
+
+  return map
+}
+
 export const reducer = (state: SidebarSectionItems, actionData: ActionType) => {
   if (actionData.type === "replace") {
     return actionData.replacementItems
@@ -226,6 +255,20 @@ export const SidebarProvider = ({
     CurrentItemsState | undefined
   >()
   const [activePath, setActivePath] = useState<string | null>("")
+  const linksMap: LinksMap = useMemo(() => {
+    return new Map([
+      ...getLinksMap(items.mobile),
+      ...getLinksMap(items.default),
+    ])
+  }, [items])
+  const findItemInSection = useCallback(findItem, [])
+  const activeItem = useMemo(() => {
+    if (activePath === null) {
+      return undefined
+    }
+
+    return linksMap.get(activePath)
+  }, [activePath, linksMap])
   const [mobileSidebarOpen, setMobileSidebarOpen] = useState<boolean>(false)
   const [sidebarTopHeight, setSidebarTopHeight] = useState(0)
   const [desktopSidebarOpen, setDesktopSidebarOpen] = useState(true)
@@ -233,35 +276,20 @@ export const SidebarProvider = ({
 
   const pathname = usePathname()
   const router = useRouter()
-  const isBrowser = useIsBrowser()
+  const { isBrowser } = useIsBrowser()
   const getResolvedScrollableElement = useCallback(() => {
     return scrollableElement || window
   }, [scrollableElement])
 
-  const findItemInSection = useCallback(findItem, [])
-
   const isItemLoaded = useCallback(
     (path: string) => {
-      const item =
-        findItemInSection(items.mobile, { path, type: "link" }) ||
-        findItemInSection(items.default, { path, type: "link" })
+      const item = linksMap.get(path)
 
       return item?.loaded || false
     },
-    [items]
+    [items, linksMap]
   )
 
-  const getActiveItem = useCallback(() => {
-    if (activePath === null) {
-      return undefined
-    }
-
-    return (
-      findItemInSection(items.mobile, { path: activePath, type: "link" }) ||
-      findItemInSection(items.default, { path: activePath, type: "link" })
-    )
-  }, [activePath, items, findItemInSection])
-
   const addItems = (newItems: SidebarItem[], options?: ActionOptionsType) => {
     dispatch({
       type: options?.parent ? "update" : "add",
@@ -322,10 +350,12 @@ export const SidebarProvider = ({
         if (!currentSidebar && item.children?.length) {
           const childSidebar =
             getCurrentSidebar(item.children) ||
-            findItem(item.children, {
-              path: activePath || undefined,
-              type: "link",
-            })
+            (activePath
+              ? findItem(item.children, {
+                  path: activePath || undefined,
+                  type: "link",
+                })
+              : undefined)
 
           if (childSidebar) {
             currentSidebar = childSidebar.isChildSidebar ? childSidebar : item
@@ -385,10 +415,16 @@ export const SidebarProvider = ({
 
     const handleScroll = () => {
       if (getScrolledTop(resolvedScrollableElement) === 0) {
-        setActivePath("")
-        // can't use next router as it doesn't support
-        // changing url without scrolling
-        history.replaceState({}, "", location.pathname)
+        const firstItemPath =
+          items.default.length && items.default[0].type === "link"
+            ? items.default[0].path
+            : ""
+        setActivePath(firstItemPath)
+        if (firstItemPath) {
+          router.push(`#${firstItemPath}`, {
+            scroll: false,
+          })
+        }
       }
     }
 
@@ -540,7 +576,7 @@ export const SidebarProvider = ({
         setMobileSidebarOpen,
         desktopSidebarOpen,
         setDesktopSidebarOpen,
-        getActiveItem,
+        activeItem,
         staticSidebarItems,
         disableActiveTransition,
         shouldHandleHashChange,

www/packages/docs-ui/src/providers/index.ts

@@ -1,5 +1,6 @@
 export * from "./AiAssistant"
 export * from "./Analytics"
+export * from "./BrowserProvider"
 export * from "./ColorMode"
 export * from "./LearningPath"
 export * from "./MainNav"