@tanstack/router-core 1.168.4 → 1.168.6

package/src/scroll-restoration.ts

@@ -1,20 +1,21 @@
 import { isServer } from '@tanstack/router-core/isServer'
-import { functionalUpdate } from './utils'
+import { functionalUpdate, isPlainObject } from './utils'
 import type { AnyRouter } from './router'
 import type { ParsedLocation } from './location'
 import type { NonNullableUpdater } from './utils'
-import type { HistoryLocation } from '@tanstack/history'
 
 export type ScrollRestorationEntry = { scrollX: number; scrollY: number }
 
-export type ScrollRestorationByElement = Record<string, ScrollRestorationEntry>
+type ScrollRestorationByElement = Record<string, ScrollRestorationEntry>
 
-export type ScrollRestorationByKey = Record<string, ScrollRestorationByElement>
+type ScrollRestorationByKey = Record<string, ScrollRestorationByElement>
 
-export type ScrollRestorationCache = {
-  state: ScrollRestorationByKey
+type ScrollRestorationCache = {
+  readonly state: ScrollRestorationByKey
   set: (updater: NonNullableUpdater<ScrollRestorationByKey>) => void
+  persist: () => void
 }
+
 export type ScrollRestorationOptions = {
   getKey?: (location: ParsedLocation) => string
   scrollBehavior?: ScrollToOptions['behavior']
@@ -22,65 +23,59 @@ export type ScrollRestorationOptions = {
 
 function getSafeSessionStorage() {
   try {
-    if (
-      typeof window !== 'undefined' &&
+    return typeof window !== 'undefined' &&
       typeof window.sessionStorage === 'object'
-    ) {
-      return window.sessionStorage
-    }
+      ? window.sessionStorage
+      : undefined
   } catch {
     // silent
+    return undefined
   }
-  return undefined
 }
 
-/** SessionStorage key used to persist scroll restoration state. */
-/** SessionStorage key used to store scroll positions across navigations. */
-/** SessionStorage key used to store scroll positions across navigations. */
+// SessionStorage key used to store scroll positions across navigations.
 export const storageKey = 'tsr-scroll-restoration-v1_3'
 
-const throttle = (fn: (...args: Array<any>) => void, wait: number) => {
-  let timeout: any
-  return (...args: Array<any>) => {
-    if (!timeout) {
-      timeout = setTimeout(() => {
-        fn(...args)
-        timeout = null
-      }, wait)
-    }
-  }
-}
-
 function createScrollRestorationCache(): ScrollRestorationCache | null {
   const safeSessionStorage = getSafeSessionStorage()
   if (!safeSessionStorage) {
     return null
   }
 
-  const persistedState = safeSessionStorage.getItem(storageKey)
-  let state: ScrollRestorationByKey = persistedState
-    ? JSON.parse(persistedState)
-    : {}
+  let state: ScrollRestorationByKey = {}
 
-  return {
-    state,
-    // This setter is simply to make sure that we set the sessionStorage right
-    // after the state is updated. It doesn't necessarily need to be a functional
-    // update.
-    set: (updater) => {
-      state = functionalUpdate(updater, state) || state
-      try {
-        safeSessionStorage.setItem(storageKey, JSON.stringify(state))
-      } catch {
+  try {
+    const parsed = JSON.parse(safeSessionStorage.getItem(storageKey) || '{}')
+    if (isPlainObject(parsed)) {
+      state = parsed as ScrollRestorationByKey
+    }
+  } catch {
+    // ignore invalid session storage payloads
+  }
+
+  const persist = () => {
+    try {
+      safeSessionStorage.setItem(storageKey, JSON.stringify(state))
+    } catch {
+      if (process.env.NODE_ENV !== 'production') {
         console.warn(
           '[ts-router] Could not persist scroll restoration state to sessionStorage.',
         )
       }
+    }
+  }
+
+  return {
+    get state() {
+      return state
+    },
+    set: (updater) => {
+      state = functionalUpdate(updater, state) || state
     },
+    persist,
   }
 }
 
-/** In-memory handle to the persisted scroll restoration cache. */
 export const scrollRestorationCache = createScrollRestorationCache()
 
 /**
@@ -89,16 +84,11 @@ export const scrollRestorationCache = createScrollRestorationCache()
  *
  * The `location.href` is used as a fallback to support the use case where the location state is not available like the initial render.
  */
-
-/**
- * Default scroll restoration cache key: location state key or full href.
- */
 export const defaultGetScrollRestorationKey = (location: ParsedLocation) => {
   return location.state.__TSR_key! || location.href
 }
 
-/** Best-effort nth-child CSS selector for a given element. */
-export function getCssSelector(el: any): string {
+function getCssSelector(el: any): string {
   const path = []
   let parent: HTMLElement
   while ((parent = el.parentNode)) {
@@ -110,117 +100,52 @@ export function getCssSelector(el: any): string {
   return `${path.reverse().join(' > ')}`.toLowerCase()
 }
 
-let ignoreScroll = false
-
-// NOTE: This function must remain pure and not use any outside variables
-// unless they are passed in as arguments. Why? Because we need to be able to
-// toString() it into a script tag to execute as early as possible in the browser
-// during SSR. Additionally, we also call it from within the router lifecycle
-export function restoreScroll({
-  storageKey,
-  key,
-  behavior,
-  shouldScrollRestoration,
-  scrollToTopSelectors,
-  location,
-}: {
-  storageKey: string
-  key?: string
-  behavior?: ScrollToOptions['behavior']
-  shouldScrollRestoration?: boolean
-  scrollToTopSelectors?: Array<string | (() => Element | null | undefined)>
-  location?: HistoryLocation
-}) {
-  let byKey: ScrollRestorationByKey
-
-  try {
-    byKey = JSON.parse(sessionStorage.getItem(storageKey) || '{}')
-  } catch (error) {
-    console.error(error)
-    return
-  }
-
-  const resolvedKey = key || window.history.state?.__TSR_key
-  const elementEntries = byKey[resolvedKey]
-
-  //
-  ignoreScroll = true
-
-  //
-  scroll: {
-    // If we have a cached entry for this location state,
-    // we always need to prefer that over the hash scroll.
-    if (
-      shouldScrollRestoration &&
-      elementEntries &&
-      Object.keys(elementEntries).length > 0
-    ) {
-      for (const elementSelector in elementEntries) {
-        const entry = elementEntries[elementSelector]!
-        if (elementSelector === 'window') {
-          window.scrollTo({
-            top: entry.scrollY,
-            left: entry.scrollX,
-            behavior,
-          })
-        } else if (elementSelector) {
-          const element = document.querySelector(elementSelector)
-          if (element) {
-            element.scrollLeft = entry.scrollX
-            element.scrollTop = entry.scrollY
-          }
-        }
+export function getElementScrollRestorationEntry(
+  router: AnyRouter,
+  options: (
+    | {
+        id: string
+        getElement?: () => Window | Element | undefined | null
       }
-
-      break scroll
-    }
-
-    // If we don't have a cached entry for the hash,
-    // Which means we've never seen this location before,
-    // we need to check if there is a hash in the URL.
-    // If there is, we need to scroll it's ID into view.
-    const hash = (location ?? window.location).hash.split('#', 2)[1]
-
-    if (hash) {
-      const hashScrollIntoViewOptions =
-        window.history.state?.__hashScrollIntoViewOptions ?? true
-
-      if (hashScrollIntoViewOptions) {
-        const el = document.getElementById(hash)
-        if (el) {
-          el.scrollIntoView(hashScrollIntoViewOptions)
-        }
+    | {
+        id?: string
+        getElement: () => Window | Element | undefined | null
       }
+  ) & {
+    getKey?: (location: ParsedLocation) => string
+  },
+): ScrollRestorationEntry | undefined {
+  const getKey = options.getKey || defaultGetScrollRestorationKey
+  const restoreKey = getKey(router.latestLocation)
+
+  if (options.id) {
+    return scrollRestorationCache?.state[restoreKey]?.[
+      `[${scrollRestorationIdAttribute}="${options.id}"]`
+    ]
+  }
 
-      break scroll
-    }
-
-    // If there is no cached entry for the hash and there is no hash in the URL,
-    // we need to scroll to the top of the page for every scrollToTop element
-    const scrollOptions = { top: 0, left: 0, behavior }
-    window.scrollTo(scrollOptions)
-    if (scrollToTopSelectors) {
-      for (const selector of scrollToTopSelectors) {
-        if (selector === 'window') continue
-        const element =
-          typeof selector === 'function'
-            ? selector()
-            : document.querySelector(selector)
-        if (element) element.scrollTo(scrollOptions)
-      }
-    }
+  const element = options.getElement?.()
+  if (!element) {
+    return
   }
 
-  //
-  ignoreScroll = false
+  return scrollRestorationCache?.state[restoreKey]?.[
+    element instanceof Window ? windowScrollTarget : getCssSelector(element)
+  ]
 }
 
-/** Setup global listeners and hooks to support scroll restoration. */
-/** Setup global listeners and hooks to support scroll restoration. */
+let ignoreScroll = false
+const windowScrollTarget = 'window'
+const scrollRestorationIdAttribute = 'data-scroll-restoration-id'
+type ScrollTarget = typeof windowScrollTarget | Element
+
 export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
   if (!scrollRestorationCache && !(isServer ?? router.isServer)) {
     return
   }
+
+  const cache = scrollRestorationCache
+
   const shouldScrollRestoration =
     force ?? router.options.scrollRestoration ?? false
 
@@ -231,173 +156,202 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
   if (
     (isServer ?? router.isServer) ||
     router.isScrollRestorationSetup ||
-    !scrollRestorationCache
+    !cache
   ) {
     return
   }
 
   router.isScrollRestorationSetup = true
-
-  //
   ignoreScroll = false
 
   const getKey =
     router.options.getScrollRestorationKey || defaultGetScrollRestorationKey
+  const trackedScrollEntries = new Map<ScrollTarget, ScrollRestorationEntry>()
 
   window.history.scrollRestoration = 'manual'
 
-  // // Create a MutationObserver to monitor DOM changes
-  // const mutationObserver = new MutationObserver(() => {
-  //   ;ignoreScroll = true
-  //   requestAnimationFrame(() => {
-  //     ;ignoreScroll = false
-
-  //     // Attempt to restore scroll position on each dom
-  //     // mutation until the user scrolls. We do this
-  //     // because dynamic content may come in at different
-  //     // ticks after the initial render and we want to
-  //     // keep up with that content as much as possible.
-  //     // As soon as the user scrolls, we no longer need
-  //     // to attempt router.
-  //     // console.log('mutation observer restoreScroll')
-  //     restoreScroll(
-  //       storageKey,
-  //       getKey(router.stores.location.state),
-  //       router.options.scrollRestorationBehavior,
-  //     )
-  //   })
-  // })
-
-  // const observeDom = () => {
-  //   // Observe changes to the entire document
-  //   mutationObserver.observe(document, {
-  //     childList: true, // Detect added or removed child nodes
-  //     subtree: true, // Monitor all descendants
-  //     characterData: true, // Detect text content changes
-  //   })
-  // }
-
-  // const unobserveDom = () => {
-  //   mutationObserver.disconnect()
-  // }
-
-  // observeDom()
-
   const onScroll = (event: Event) => {
-    // unobserveDom()
-
     if (ignoreScroll || !router.isScrollRestoring) {
       return
     }
 
-    let elementSelector = ''
-
     if (event.target === document || event.target === window) {
-      elementSelector = 'window'
+      trackedScrollEntries.set(windowScrollTarget, {
+        scrollX: window.scrollX || 0,
+        scrollY: window.scrollY || 0,
+      })
     } else {
-      const attrId = (event.target as Element).getAttribute(
-        'data-scroll-restoration-id',
-      )
-
-      if (attrId) {
-        elementSelector = `[data-scroll-restoration-id="${attrId}"]`
-      } else {
-        elementSelector = getCssSelector(event.target)
-      }
+      const target = event.target as Element
+      trackedScrollEntries.set(target, {
+        scrollX: target.scrollLeft || 0,
+        scrollY: target.scrollTop || 0,
+      })
     }
+  }
 
-    const restoreKey = getKey(router.stores.location.state)
+  // Snapshot the current page's tracked scroll targets before navigation or unload.
+  const snapshotCurrentScrollTargets = (restoreKey?: string) => {
+    if (
+      !router.isScrollRestoring ||
+      !restoreKey ||
+      trackedScrollEntries.size === 0 ||
+      !cache
+    ) {
+      return
+    }
 
-    scrollRestorationCache.set((state) => {
-      const keyEntry = (state[restoreKey] ||= {} as ScrollRestorationByElement)
+    const keyEntry = (cache.state[restoreKey] ||=
+      {} as ScrollRestorationByElement)
 
-      const elementEntry = (keyEntry[elementSelector] ||=
-        {} as ScrollRestorationEntry)
+    for (const [target, position] of trackedScrollEntries) {
+      let selector: string | undefined
 
-      if (elementSelector === 'window') {
-        elementEntry.scrollX = window.scrollX || 0
-        elementEntry.scrollY = window.scrollY || 0
-      } else if (elementSelector) {
-        const element = document.querySelector(elementSelector)
-        if (element) {
-          elementEntry.scrollX = element.scrollLeft || 0
-          elementEntry.scrollY = element.scrollTop || 0
-        }
+      if (target === windowScrollTarget) {
+        selector = windowScrollTarget
+      } else if (target.isConnected) {
+        const attrId = target.getAttribute(scrollRestorationIdAttribute)
+        selector = attrId
+          ? `[${scrollRestorationIdAttribute}="${attrId}"]`
+          : getCssSelector(target)
       }
 
-      return state
-    })
-  }
+      if (!selector) {
+        continue
+      }
 
-  // Throttle the scroll event to avoid excessive updates
-  if (typeof document !== 'undefined') {
-    document.addEventListener('scroll', throttle(onScroll, 100), true)
+      keyEntry[selector] = position
+    }
   }
 
-  router.subscribe('onRendered', (event) => {
-    // unobserveDom()
+  document.addEventListener('scroll', onScroll, true)
+  router.subscribe('onBeforeLoad', (event) => {
+    snapshotCurrentScrollTargets(
+      event.fromLocation ? getKey(event.fromLocation) : undefined,
+    )
+    trackedScrollEntries.clear()
+  })
+  window.addEventListener('pagehide', () => {
+    snapshotCurrentScrollTargets(
+      getKey(
+        router.stores.resolvedLocation.state ?? router.stores.location.state,
+      ),
+    )
+    cache.persist()
+  })
 
+  // Restore destination scroll after the new route has rendered.
+  router.subscribe('onRendered', (event) => {
     const cacheKey = getKey(event.toLocation)
+    const behavior = router.options.scrollRestorationBehavior
+    const scrollToTopSelectors = router.options.scrollToTopSelectors
+    trackedScrollEntries.clear()
 
-    // If the user doesn't want to restore the scroll position,
-    // we don't need to do anything.
     if (!router.resetNextScroll) {
       router.resetNextScroll = true
       return
     }
-    if (typeof router.options.scrollRestoration === 'function') {
-      const shouldRestore = router.options.scrollRestoration({
-        location: router.latestLocation,
-      })
-      if (!shouldRestore) {
-        return
-      }
+
+    if (
+      typeof router.options.scrollRestoration === 'function' &&
+      !router.options.scrollRestoration({ location: router.latestLocation })
+    ) {
+      return
     }
 
-    restoreScroll({
-      storageKey,
-      key: cacheKey,
-      behavior: router.options.scrollRestorationBehavior,
-      shouldScrollRestoration: router.isScrollRestoring,
-      scrollToTopSelectors: router.options.scrollToTopSelectors,
-      location: router.history.location,
-    })
+    ignoreScroll = true
+
+    try {
+      const elementEntries = router.isScrollRestoring
+        ? cache.state[cacheKey]
+        : undefined
+      let restored = false
+
+      if (elementEntries) {
+        for (const elementSelector in elementEntries) {
+          const entry = elementEntries[elementSelector]
+
+          if (!isPlainObject(entry)) {
+            continue
+          }
+
+          const { scrollX, scrollY } = entry as {
+            scrollX?: unknown
+            scrollY?: unknown
+          }
+
+          if (!Number.isFinite(scrollX) || !Number.isFinite(scrollY)) {
+            continue
+          }
+
+          if (elementSelector === windowScrollTarget) {
+            window.scrollTo({
+              top: scrollY as number,
+              left: scrollX as number,
+              behavior,
+            })
+            restored = true
+          } else if (elementSelector) {
+            let element
+
+            try {
+              element = document.querySelector(elementSelector)
+            } catch {
+              continue
+            }
+
+            if (element) {
+              element.scrollLeft = scrollX as number
+              element.scrollTop = scrollY as number
+              restored = true
+            }
+          }
+        }
+      }
+
+      if (!restored) {
+        const hash = router.history.location.hash.slice(1)
+
+        if (hash) {
+          const hashScrollIntoViewOptions =
+            window.history.state?.__hashScrollIntoViewOptions ?? true
+
+          if (hashScrollIntoViewOptions) {
+            const el = document.getElementById(hash)
+            if (el) {
+              el.scrollIntoView(hashScrollIntoViewOptions)
+            }
+          }
+        } else {
+          const scrollOptions = {
+            top: 0,
+            left: 0,
+            behavior,
+          }
+
+          window.scrollTo(scrollOptions)
+          if (scrollToTopSelectors) {
+            for (const selector of scrollToTopSelectors) {
+              if (selector === windowScrollTarget) continue
+              const element =
+                typeof selector === 'function'
+                  ? selector()
+                  : document.querySelector(selector)
+              if (element) {
+                element.scrollTo(scrollOptions)
+              }
+            }
+          }
+        }
+      }
+    } finally {
+      ignoreScroll = false
+    }
 
     if (router.isScrollRestoring) {
-      // Mark the location as having been seen
-      scrollRestorationCache.set((state) => {
+      cache.set((state) => {
         state[cacheKey] ||= {} as ScrollRestorationByElement
-
         return state
       })
     }
   })
 }
-
-/**
- * @private
- * Handles hash-based scrolling after navigation completes.
- * To be used in framework-specific <Transitioner> components during the onResolved event.
- *
- * Provides hash scrolling for programmatic navigation when default browser handling is prevented.
- * @param router The router instance containing current location and state
- */
-/**
- * @private
- * Handles hash-based scrolling after navigation completes.
- * To be used in framework-specific Transitioners.
- */
-export function handleHashScroll(router: AnyRouter) {
-  if (typeof document !== 'undefined' && (document as any).querySelector) {
-    const location = router.stores.location.state
-    const hashScrollIntoViewOptions =
-      location.state.__hashScrollIntoViewOptions ?? true
-
-    if (hashScrollIntoViewOptions && location.hash !== '') {
-      const el = document.getElementById(location.hash)
-      if (el) {
-        el.scrollIntoView(hashScrollIntoViewOptions)
-      }
-    }
-  }
-}