docs: fix weird scroll behavior (#11668)

www/packages/docs-ui/src/components/Heading/H1/index.tsx

@@ -10,7 +10,7 @@ export const H1 = ({ className, ...props }: H1Props) => {
     <h1
       className={clsx(
         "h1-docs [&_code]:!h1-docs [&_code]:!font-mono mb-docs_1 text-medusa-fg-base",
-        props.id && "scroll-m-56",
+        props.id && "scroll-m-docs_7",
         className
       )}
       {...props}

www/packages/docs-ui/src/components/Heading/H2/index.tsx

@@ -3,7 +3,7 @@
 import clsx from "clsx"
 import React from "react"
 import { CopyButton, Link } from "@/components"
-import { useHeadingUrl } from "../../.."
+import { useHeadingUrl, useLayout } from "../../.."
 
 type H2Props = React.HTMLAttributes<HTMLHeadingElement> & {
   id?: string
@@ -11,6 +11,8 @@ type H2Props = React.HTMLAttributes<HTMLHeadingElement> & {
 }
 
 export const H2 = ({ className, children, passRef, ...props }: H2Props) => {
+  const { showCollapsedNavbar } = useLayout()
+
   const copyText = useHeadingUrl({
     id: props.id || "",
   })
@@ -18,7 +20,11 @@ export const H2 = ({ className, children, passRef, ...props }: H2Props) => {
     <h2
       className={clsx(
         "h2-docs [&_code]:!h2-docs [&_code]:!font-mono mb-docs_1 mt-docs_2 text-medusa-fg-base",
-        props.id && "group/h2 scroll-m-56",
+        props.id && [
+          "group/h2",
+          showCollapsedNavbar && "scroll-m-docs_7",
+          !showCollapsedNavbar && "scroll-m-56",
+        ],
         className
       )}
       {...props}

www/packages/docs-ui/src/components/Heading/H3/index.tsx

@@ -3,19 +3,24 @@
 import clsx from "clsx"
 import React from "react"
 import { CopyButton, Link } from "@/components"
-import { useHeadingUrl } from "../../.."
+import { useHeadingUrl, useLayout } from "../../.."
 
 type H3Props = React.HTMLAttributes<HTMLHeadingElement> & {
   id?: string
 }
 
 export const H3 = ({ className, children, ...props }: H3Props) => {
+  const { showCollapsedNavbar } = useLayout()
   const copyText = useHeadingUrl({ id: props.id || "" })
   return (
     <h3
       className={clsx(
         "h3-docs [&_code]:!h3-docs [&_code]:!font-mono my-docs_1 text-medusa-fg-base",
-        props.id && "group/h3 scroll-m-56",
+        props.id && [
+          "group/h3",
+          showCollapsedNavbar && "scroll-m-docs_7",
+          !showCollapsedNavbar && "scroll-m-56",
+        ],
         className
       )}
       {...props}

www/packages/docs-ui/src/components/Toc/index.tsx

@@ -7,6 +7,7 @@ import {
   isElmWindow,
   useActiveOnScroll,
   useIsBrowser,
+  useLayout,
   useScrollController,
 } from "../.."
 import { TocList } from "./List"
@@ -20,6 +21,7 @@ export const Toc = () => {
   const { items: headingItems, activeItemId } = useActiveOnScroll({})
   const [maxHeight, setMaxHeight] = useState(0)
   const { scrollableElement } = useScrollController()
+  const { showCollapsedNavbar } = useLayout()
 
   const formatHeadingContent = (content: string | null): string => {
     return content?.replaceAll(/#$/g, "") || ""
@@ -44,10 +46,11 @@ export const Toc = () => {
   }, [headingItems])
 
   const handleResize = () => {
+    const extraMargin = showCollapsedNavbar ? 112 : 56
     const offset =
       (scrollableElement instanceof HTMLElement
         ? scrollableElement.offsetTop
-        : 0) + 56
+        : 0) + extraMargin
 
     setMaxHeight(
       (isElmWindow(scrollableElement)

www/packages/docs-ui/src/hooks/use-page-scroll-manager/index.tsx

@@ -30,7 +30,9 @@ export const usePageScrollManager = () => {
           ? document.getElementById(location.hash.replace("#", ""))
           : undefined
 
-      targetElm?.scrollIntoView()
+      scrollableElement?.scrollTo({
+        top: targetElm ? targetElm.offsetTop : 0,
+      })
     }
   }
 

www/packages/docs-ui/src/hooks/use-scroll-utils/index.tsx

@@ -21,6 +21,7 @@ import React, {
 } from "react"
 import { getScrolledTop as getScrolledTopUtil, isElmWindow } from "../../utils"
 import { useKeyboardShortcut } from "../use-keyboard-shortcut"
+import { useLayout } from "../../providers"
 
 type EventFunc = (...args: never[]) => unknown
 
@@ -73,6 +74,7 @@ function useScrollControllerContextValue({
   restoreScrollOnReload?: boolean
 }): ScrollController {
   const scrollEventsEnabledRef = useRef(true)
+  const { showCollapsedNavbar } = useLayout()
 
   const [scrollableElement, setScrollableElement] = useState<
     Element | Window | undefined
@@ -92,6 +94,11 @@ function useScrollControllerContextValue({
     scrollToTop(elm.offsetTop)
   }
 
+  const topMargin = useMemo(() => {
+    // might need a better way to set these static values
+    return showCollapsedNavbar ? 112 : 56
+  }, [showCollapsedNavbar])
+
   const scrollToTop = (top: number, parentTop?: number) => {
     const parentOffsetTop =
       parentTop !== undefined
@@ -103,9 +110,7 @@ function useScrollControllerContextValue({
             : 0
 
     scrollableElement?.scrollTo({
-      // 56 is the height of the navbar
+      top: top - parentOffsetTop - topMargin,
-      // might need a better way to determine it.
-      top: top - parentOffsetTop - 56,
       behavior: "instant",
     })
   }