@tanstack/react-router 1.98.0 → 1.98.3

package/src/scroll-restoration.tsx

@@ -1,241 +1,327 @@
-import * as React from 'react'
 import { functionalUpdate } from '@tanstack/router-core'
 import { useRouter } from './useRouter'
+import { ScriptOnce } from './ScriptOnce'
+import type { AnyRouter } from './router'
 import type { NonNullableUpdater, ParsedLocation } from '@tanstack/router-core'
 
-const useLayoutEffect =
-  typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect
+export type ScrollRestorationEntry = { scrollX: number; scrollY: number }
 
-const windowKey = 'window'
-const delimiter = '___'
+export type ScrollRestorationByElement = Record<string, ScrollRestorationEntry>
 
-let weakScrolledElements = new WeakSet<any>()
+export type ScrollRestorationByKey = Record<string, ScrollRestorationByElement>
 
-type CacheValue = Record<string, { scrollX: number; scrollY: number }>
-type CacheState = {
-  cached: CacheValue
-  next: CacheValue
+export type ScrollRestorationCache = {
+  state: ScrollRestorationByKey
+  set: (updater: NonNullableUpdater<ScrollRestorationByKey>) => void
 }
-
-type Cache = {
-  state: CacheState
-  set: (updater: NonNullableUpdater<CacheState>) => void
+export type ScrollRestorationOptions = {
+  getKey?: (location: ParsedLocation) => string
+  scrollBehavior?: ScrollToOptions['behavior']
 }
 
+export const storageKey = 'tsr-scroll-restoration-v1_3'
 const sessionsStorage = typeof window !== 'undefined' && window.sessionStorage
-
-const cache: Cache = sessionsStorage
+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)
+    }
+  }
+}
+export const scrollRestorationCache: ScrollRestorationCache = sessionsStorage
   ? (() => {
-      const storageKey = 'tsr-scroll-restoration-v2'
-
-      const state: CacheState = JSON.parse(
-        window.sessionStorage.getItem(storageKey) || 'null',
-      ) || { cached: {}, next: {} }
+      const state: ScrollRestorationByKey =
+        JSON.parse(window.sessionStorage.getItem(storageKey) || 'null') || {}
 
       return {
         state,
-        set: (updater) => {
-          cache.state = functionalUpdate(updater, cache.state)
-          window.sessionStorage.setItem(storageKey, JSON.stringify(cache.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) => (
+          (scrollRestorationCache.state =
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            functionalUpdate(updater, scrollRestorationCache.state) ||
+            scrollRestorationCache.state),
+          window.sessionStorage.setItem(
+            storageKey,
+            JSON.stringify(scrollRestorationCache.state),
+          )
+        ),
       }
     })()
   : (undefined as any)
-
-export type ScrollRestorationOptions = {
-  getKey?: (location: ParsedLocation) => string
-  scrollBehavior?: ScrollToOptions['behavior']
-}
-
 /**
  * The default `getKey` function for `useScrollRestoration`.
  * It returns the `key` from the location state or the `href` of the location.
  *
  * The `location.href` is used as a fallback to support the use case where the location state is not available like the initial render.
  */
-const defaultGetKey = (location: ParsedLocation) => {
+
+export const defaultGetScrollRestorationKey = (location: ParsedLocation) => {
   return location.state.key! || location.href
 }
 
-export function useScrollRestoration(options?: ScrollRestorationOptions) {
-  const router = useRouter()
-
-  useLayoutEffect(() => {
-    const getKey = options?.getKey || defaultGetKey
-
-    const { history } = window
-    history.scrollRestoration = 'manual'
+export function getCssSelector(el: any): string {
+  const path = []
+  let parent
+  while ((parent = el.parentNode)) {
+    path.unshift(
+      `${el.tagName}:nth-child(${([].indexOf as any).call(parent.children, el) + 1})`,
+    )
+    el = parent
+  }
+  return `${path.join(' > ')}`.toLowerCase()
+}
 
-    const onScroll = (event: Event) => {
-      if (weakScrolledElements.has(event.target)) return
-      weakScrolledElements.add(event.target)
+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: string,
+  key?: string,
+  behavior?: ScrollToOptions['behavior'],
+  shouldScrollRestoration?: boolean,
+) {
+  let byKey: ScrollRestorationByKey
 
-      let elementSelector = ''
+  try {
+    byKey = JSON.parse(sessionStorage.getItem(storageKey) || '{}')
+  } catch (error: any) {
+    console.error(error)
+    return
+  }
 
-      if (event.target === document || event.target === window) {
-        elementSelector = windowKey
-      } 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 resolvedKey = key || window.history.state?.key
+  const elementEntries = byKey[resolvedKey]
+
+  //
+  ignoreScroll = true
+
+  //
+  ;(() => {
+    // If we have a cached entry for this location state,
+    // we always need to prefer that over the hash scroll.
+    if (shouldScrollRestoration && elementEntries) {
+      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
+          }
         }
       }
 
-      if (!cache.state.next[elementSelector]) {
-        cache.set((c) => ({
-          ...c,
-          next: {
-            ...c.next,
-            [elementSelector]: {
-              scrollX: NaN,
-              scrollY: NaN,
-            },
-          },
-        }))
-      }
+      return
     }
 
-    if (typeof document !== 'undefined') {
-      document.addEventListener('scroll', onScroll, true)
-    }
+    // 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 = window.location.hash.split('#')[1]
 
-    const unsubOnBeforeLoad = router.subscribe('onBeforeLoad', (event) => {
-      if (event.hrefChanged) {
-        const restoreKey = getKey(event.fromLocation)
-        for (const elementSelector in cache.state.next) {
-          const entry = cache.state.next[elementSelector]!
-          if (elementSelector === windowKey) {
-            entry.scrollX = window.scrollX || 0
-            entry.scrollY = window.scrollY || 0
-          } else if (elementSelector) {
-            const element = document.querySelector(elementSelector)
-            entry.scrollX = element?.scrollLeft || 0
-            entry.scrollY = element?.scrollTop || 0
-          }
+    if (hash) {
+      const hashScrollIntoViewOptions =
+        (window.history.state || {}).__hashScrollIntoViewOptions ?? true
 
-          cache.set((c) => {
-            const next = { ...c.next }
-            delete next[elementSelector]
-
-            return {
-              ...c,
-              next,
-              cached: {
-                ...c.cached,
-                [[restoreKey, elementSelector].join(delimiter)]: entry,
-              },
-            }
-          })
+      if (hashScrollIntoViewOptions) {
+        const el = document.getElementById(hash)
+        if (el) {
+          el.scrollIntoView(hashScrollIntoViewOptions)
         }
       }
+
+      return
+    }
+
+    // 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.
+    window.scrollTo({
+      top: 0,
+      left: 0,
+      behavior,
     })
+  })()
 
-    const unsubOnBeforeRouteMount = router.subscribe(
-      'onBeforeRouteMount',
-      (event) => {
-        if (event.hrefChanged) {
-          if (!router.resetNextScroll) {
-            return
-          }
+  //
+  ignoreScroll = false
+}
 
-          router.resetNextScroll = true
-
-          const restoreKey = getKey(event.toLocation)
-          let windowRestored = false
-
-          for (const cacheKey in cache.state.cached) {
-            const entry = cache.state.cached[cacheKey]!
-            const [key, elementSelector] = cacheKey.split(delimiter)
-            if (key === restoreKey) {
-              if (elementSelector === windowKey) {
-                windowRestored = true
-                window.scrollTo({
-                  top: entry.scrollY,
-                  left: entry.scrollX,
-                  behavior: options?.scrollBehavior,
-                })
-              } else if (elementSelector) {
-                const element = document.querySelector(elementSelector)
-                if (element) {
-                  element.scrollLeft = entry.scrollX
-                  element.scrollTop = entry.scrollY
-                }
-              }
-            }
-          }
+export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
+  const shouldScrollRestoration =
+    force ?? router.options.scrollRestoration ?? false
 
-          if (!windowRestored) {
-            window.scrollTo(0, 0)
-          }
+  if (shouldScrollRestoration) {
+    router.isScrollRestoring = true
+  }
 
-          cache.set((c) => ({ ...c, next: {} }))
-          weakScrolledElements = new WeakSet<any>()
-        }
-      },
-    )
+  if (typeof document === 'undefined' || router.isScrollRestorationSetup) {
+    return
+  }
 
-    return () => {
-      document.removeEventListener('scroll', onScroll)
-      unsubOnBeforeLoad()
-      unsubOnBeforeRouteMount()
+  router.isScrollRestorationSetup = true
+
+  //
+  ignoreScroll = false
+
+  const getKey =
+    router.options.getScrollRestorationKey || defaultGetScrollRestorationKey
+
+  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.state.location),
+  //       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
     }
-  }, [options?.getKey, options?.scrollBehavior, router])
-}
 
-export function ScrollRestoration(props: ScrollRestorationOptions) {
-  useScrollRestoration(props)
-  return null
-}
+    let elementSelector = ''
 
-export function useElementScrollRestoration(
-  options: (
-    | {
-        id: string
-        getElement?: () => Element | undefined | null
+    if (event.target === document || event.target === window) {
+      elementSelector = 'window'
+    } 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)
       }
-    | {
-        id?: string
-        getElement: () => Element | undefined | null
+    }
+
+    const restoreKey = getKey(router.state.location)
+
+    scrollRestorationCache.set((state) => {
+      const keyEntry = (state[restoreKey] =
+        state[restoreKey] || ({} as ScrollRestorationByElement))
+
+      const elementEntry = (keyEntry[elementSelector] =
+        keyEntry[elementSelector] || ({} as ScrollRestorationEntry))
+
+      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
+        }
       }
-  ) & {
-    getKey?: (location: ParsedLocation) => string
-  },
-) {
-  const router = useRouter()
-  const getKey = options.getKey || defaultGetKey
 
-  let elementSelector = ''
+      return state
+    })
+  }
+
+  // Throttle the scroll event to avoid excessive updates
+  if (typeof document !== 'undefined') {
+    document.addEventListener('scroll', throttle(onScroll, 100), true)
+  }
+
+  router.subscribe('onRendered', (event) => {
+    // unobserveDom()
 
-  if (options.id) {
-    elementSelector = `[data-scroll-restoration-id="${options.id}"]`
-  } else {
-    const element = options.getElement?.()
-    if (!element) {
+    const cacheKey = getKey(event.toLocation)
+
+    // 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
     }
-    elementSelector = getCssSelector(element)
-  }
 
-  const restoreKey = getKey(router.latestLocation)
-  const cacheKey = [restoreKey, elementSelector].join(delimiter)
-  return cache.state.cached[cacheKey]
+    restoreScroll(
+      storageKey,
+      cacheKey,
+      router.options.scrollRestorationBehavior,
+      router.isScrollRestoring,
+    )
+
+    if (router.isScrollRestoring) {
+      // Mark the location as having been seen
+      scrollRestorationCache.set((state) => {
+        state[cacheKey] = state[cacheKey] || ({} as ScrollRestorationByElement)
+
+        return state
+      })
+    }
+  })
 }
 
-function getCssSelector(el: any): string {
-  const path = []
-  let parent
-  while ((parent = el.parentNode)) {
-    path.unshift(
-      `${el.tagName}:nth-child(${
-        ([].indexOf as any).call(parent.children, el) + 1
-      })`,
-    )
-    el = parent
+export function ScrollRestoration() {
+  const router = useRouter()
+  const getKey =
+    router.options.getScrollRestorationKey || defaultGetScrollRestorationKey
+  const userKey = getKey(router.latestLocation)
+  const resolvedKey =
+    userKey !== defaultGetScrollRestorationKey(router.latestLocation)
+      ? userKey
+      : null
+
+  if (!router.isScrollRestoring || !router.isServer) {
+    return null
   }
-  return `${path.join(' > ')}`.toLowerCase()
+
+  return (
+    <ScriptOnce
+      children={`(${restoreScroll.toString()})(${JSON.stringify(storageKey)},${JSON.stringify(resolvedKey)}, undefined, true)`}
+      log={false}
+    />
+  )
 }