@tanstack/router-core 1.171.2 → 1.171.4

package/src/scroll-restoration.ts

@@ -1,8 +1,7 @@
 import { isServer } from '@tanstack/router-core/isServer'
-import { functionalUpdate, isPlainObject } from './utils'
+import { locationHistoryActions } from './router'
 import type { AnyRouter } from './router'
 import type { ParsedLocation } from './location'
-import type { NonNullableUpdater } from './utils'
 
 export type ScrollRestorationEntry = { scrollX: number; scrollY: number }
 
@@ -10,12 +9,6 @@ type ScrollRestorationByElement = Record<string, ScrollRestorationEntry>
 
 type ScrollRestorationByKey = Record<string, ScrollRestorationByElement>
 
-type ScrollRestorationCache = {
-  readonly state: ScrollRestorationByKey
-  set: (updater: NonNullableUpdater<ScrollRestorationByKey>) => void
-  persist: () => void
-}
-
 export type ScrollRestorationOptions = {
   getKey?: (location: ParsedLocation) => string
   scrollBehavior?: ScrollToOptions['behavior']
@@ -23,60 +16,46 @@ export type ScrollRestorationOptions = {
 
 function getSafeSessionStorage() {
   try {
-    return typeof window !== 'undefined' &&
-      typeof window.sessionStorage === 'object'
-      ? window.sessionStorage
-      : undefined
+    // Accessing sessionStorage itself can throw SecurityError in locked-down
+    // contexts, e.g. sandboxed/opaque origins or blocked storage policies.
+    return sessionStorage
   } catch {
-    // silent
-    return undefined
+    return
   }
 }
 
 // SessionStorage key used to store scroll positions across navigations.
 export const storageKey = 'tsr-scroll-restoration-v1_3'
+const safeSessionStorage = getSafeSessionStorage()
 
-function createScrollRestorationCache(): ScrollRestorationCache | null {
-  const safeSessionStorage = getSafeSessionStorage()
-  if (!safeSessionStorage) {
-    return null
-  }
-
-  let state: ScrollRestorationByKey = {}
-
+function createScrollRestorationCache() {
   try {
-    const parsed = JSON.parse(safeSessionStorage.getItem(storageKey) || '{}')
-    if (isPlainObject(parsed)) {
-      state = parsed as ScrollRestorationByKey
-    }
+    return JSON.parse(
+      safeSessionStorage?.getItem(storageKey) || '{}',
+    ) as ScrollRestorationByKey
   } catch {
     // ignore invalid session storage payloads
+    return {}
   }
+}
 
-  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.',
-        )
-      }
+function persistScrollRestorationCache() {
+  try {
+    safeSessionStorage?.setItem(
+      storageKey,
+      JSON.stringify(scrollRestorationCache),
+    )
+  } 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,
-  }
 }
 
-export const scrollRestorationCache = createScrollRestorationCache()
+const scrollRestorationCache = /* @__PURE__ */ createScrollRestorationCache()
+const scrollRestorationIdAttribute = 'data-scroll-restoration-id'
 
 /**
  * The default `getKey` function for `useScrollRestoration`.
@@ -88,16 +67,29 @@ export const defaultGetScrollRestorationKey = (location: ParsedLocation) => {
   return location.state.__TSR_key! || location.href
 }
 
-function getCssSelector(el: any): string {
-  const path = []
+function getScrollRestorationSelector(element: Element): string {
+  const attrId = element.getAttribute(scrollRestorationIdAttribute)
+  if (attrId) {
+    return `[${scrollRestorationIdAttribute}="${attrId}"]`
+  }
+
+  let selector = ''
+  let el: any = element
   let parent: HTMLElement
+
   while ((parent = el.parentNode)) {
-    path.push(
-      `${el.tagName}:nth-child(${Array.prototype.indexOf.call(parent.children, el) + 1})`,
-    )
+    let index = 1
+    let sibling = el
+    while ((sibling = sibling.previousElementSibling)) {
+      index++
+    }
+
+    const part = `${el.localName}:nth-child(${index})`
+    selector = selector ? `${part} > ${selector}` : part
     el = parent
   }
-  return `${path.reverse().join(' > ')}`.toLowerCase()
+
+  return selector
 }
 
 export function getElementScrollRestorationEntry(
@@ -117,11 +109,14 @@ export function getElementScrollRestorationEntry(
 ): ScrollRestorationEntry | undefined {
   const getKey = options.getKey || defaultGetScrollRestorationKey
   const restoreKey = getKey(router.latestLocation)
+  const entries = scrollRestorationCache[restoreKey]
+
+  if (!entries) {
+    return
+  }
 
   if (options.id) {
-    return scrollRestorationCache?.state[restoreKey]?.[
-      `[${scrollRestorationIdAttribute}="${options.id}"]`
-    ]
+    return entries[`[${scrollRestorationIdAttribute}="${options.id}"]`]
   }
 
   const element = options.getElement?.()
@@ -129,35 +124,55 @@ export function getElementScrollRestorationEntry(
     return
   }
 
-  return scrollRestorationCache?.state[restoreKey]?.[
-    element instanceof Window ? windowScrollTarget : getCssSelector(element)
+  return entries[
+    element === window
+      ? windowScrollTarget
+      : getScrollRestorationSelector(element as Element)
   ]
 }
 
 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
+function getElement(selector: string | (() => Element | null | undefined)) {
+  try {
+    return typeof selector === 'function'
+      ? selector()
+      : document.querySelector(selector)
+  } catch {}
+  return
+}
+
+function getScrollToTopElements(
+  scrollToTopSelectors: NonNullable<
+    AnyRouter['options']['scrollToTopSelectors']
+  >,
+): Array<Element> {
+  const elements: Array<Element> = []
+
+  for (const selector of scrollToTopSelectors) {
+    if (selector === windowScrollTarget) {
+      continue
+    }
+
+    const element = getElement(selector)
+    if (element) {
+      elements.push(element)
+    }
   }
 
-  const cache = scrollRestorationCache
+  return elements
+}
 
-  const shouldScrollRestoration =
-    force ?? router.options.scrollRestoration ?? false
+export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
+  // Keep hash/top scrolling active even when sessionStorage is unavailable.
 
-  if (shouldScrollRestoration) {
+  if (force ?? router.options.scrollRestoration) {
     router.isScrollRestoring = true
   }
 
-  if (
-    (isServer ?? router.isServer) ||
-    router.isScrollRestorationSetup ||
-    !cache
-  ) {
+  if ((isServer ?? router.isServer) || router.isScrollRestorationSetup) {
     return
   }
 
@@ -167,88 +182,77 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
   const getKey =
     router.options.getScrollRestorationKey || defaultGetScrollRestorationKey
   const trackedScrollEntries = new Map<ScrollTarget, ScrollRestorationEntry>()
+  const setTrackedScrollEntry = (
+    target: ScrollTarget,
+    scrollX: number,
+    scrollY: number,
+  ) => {
+    const entry =
+      trackedScrollEntries.get(target) || ({} as ScrollRestorationEntry)
+    entry.scrollX = scrollX
+    entry.scrollY = scrollY
+    trackedScrollEntries.set(target, entry)
+  }
 
-  window.history.scrollRestoration = 'manual'
+  history.scrollRestoration = 'manual'
 
   const onScroll = (event: Event) => {
     if (ignoreScroll || !router.isScrollRestoring) {
       return
     }
 
-    if (event.target === document || event.target === window) {
-      trackedScrollEntries.set(windowScrollTarget, {
-        scrollX: window.scrollX || 0,
-        scrollY: window.scrollY || 0,
-      })
+    if (event.target === document) {
+      setTrackedScrollEntry(windowScrollTarget, scrollX, scrollY)
     } else {
       const target = event.target as Element
-      trackedScrollEntries.set(target, {
-        scrollX: target.scrollLeft || 0,
-        scrollY: target.scrollTop || 0,
-      })
+      setTrackedScrollEntry(target, target.scrollLeft, target.scrollTop)
     }
   }
 
   // Snapshot the current page's tracked scroll targets before navigation or unload.
-  const snapshotCurrentScrollTargets = (restoreKey?: string) => {
-    if (
-      !router.isScrollRestoring ||
-      !restoreKey ||
-      trackedScrollEntries.size === 0 ||
-      !cache
-    ) {
+  const snapshotCurrentScrollTargets = (restoreKey: string) => {
+    if (!router.isScrollRestoring) {
       return
     }
 
-    const keyEntry = (cache.state[restoreKey] ||=
+    const keyEntry = (scrollRestorationCache[restoreKey] ||=
       {} as ScrollRestorationByElement)
 
     for (const [target, position] of trackedScrollEntries) {
-      let selector: string | undefined
-
       if (target === windowScrollTarget) {
-        selector = windowScrollTarget
+        keyEntry[windowScrollTarget] = position
       } else if (target.isConnected) {
-        const attrId = target.getAttribute(scrollRestorationIdAttribute)
-        selector = attrId
-          ? `[${scrollRestorationIdAttribute}="${attrId}"]`
-          : getCssSelector(target)
-      }
-
-      if (!selector) {
-        continue
+        keyEntry[getScrollRestorationSelector(target)] = position
       }
-
-      keyEntry[selector] = position
     }
   }
 
   document.addEventListener('scroll', onScroll, true)
   router.subscribe('onBeforeLoad', (event) => {
-    snapshotCurrentScrollTargets(
-      event.fromLocation ? getKey(event.fromLocation) : undefined,
-    )
+    if (event.fromLocation) {
+      snapshotCurrentScrollTargets(getKey(event.fromLocation))
+    }
     trackedScrollEntries.clear()
   })
-  window.addEventListener('pagehide', () => {
+  addEventListener('pagehide', () => {
     snapshotCurrentScrollTargets(
       getKey(
         router.stores.resolvedLocation.get() ?? router.stores.location.get(),
       ),
     )
-    cache.persist()
+    persistScrollRestorationCache()
   })
 
   // 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
+    const shouldResetScroll = router.resetNextScroll
+    let scrollToTopElements: Array<Element> | undefined
     trackedScrollEntries.clear()
 
-    if (!router.resetNextScroll) {
+    if (!shouldResetScroll) {
       router.resetNextScroll = true
-      return
     }
 
     if (
@@ -258,68 +262,98 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
       return
     }
 
+    const cacheKey = getKey(event.toLocation)
+    const fromCacheKey = event.fromLocation && getKey(event.fromLocation)
+
+    if (router.isScrollRestoring && fromCacheKey && fromCacheKey !== cacheKey) {
+      const fromElementEntries = scrollRestorationCache[fromCacheKey]
+
+      if (fromElementEntries) {
+        let toElementEntries = scrollRestorationCache[cacheKey]
+
+        for (const elementSelector in fromElementEntries) {
+          if (elementSelector === windowScrollTarget) {
+            if (shouldResetScroll) {
+              continue
+            }
+          } else {
+            const element = getElement(elementSelector)
+            if (!element) {
+              continue
+            }
+
+            if (shouldResetScroll && scrollToTopSelectors) {
+              scrollToTopElements ??=
+                getScrollToTopElements(scrollToTopSelectors)
+              if (scrollToTopElements.includes(element)) {
+                continue
+              }
+            }
+          }
+
+          if (!toElementEntries) {
+            toElementEntries = scrollRestorationCache[cacheKey] =
+              {} as ScrollRestorationByElement
+          }
+
+          toElementEntries[elementSelector] ??=
+            fromElementEntries[elementSelector]!
+        }
+      }
+    }
+
+    if (!shouldResetScroll) {
+      return
+    }
+
     ignoreScroll = true
 
     try {
+      const hash = event.toLocation.hash
+      const hashScrollIntoViewOptions =
+        event.toLocation.state.__hashScrollIntoViewOptions ?? true
+      const action = locationHistoryActions.get(event.toLocation)
+      const skipWindowRestore =
+        hash &&
+        hashScrollIntoViewOptions &&
+        (action === 'PUSH' || action === 'REPLACE')
+
       const elementEntries = router.isScrollRestoring
-        ? cache.state[cacheKey]
+        ? scrollRestorationCache[cacheKey]
         : undefined
-      let restored = false
+      let windowRestored = 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
-          }
+          const { scrollX, scrollY } = elementEntries[elementSelector]!
 
           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 {
+            if (skipWindowRestore) {
               continue
             }
 
+            scrollTo({
+              top: scrollY,
+              left: scrollX,
+              behavior,
+            })
+            windowRestored = true
+          } else {
+            const element = getElement(elementSelector)
             if (element) {
-              element.scrollLeft = scrollX as number
-              element.scrollTop = scrollY as number
-              restored = true
+              element.scrollLeft = scrollX
+              element.scrollTop = scrollY
             }
           }
         }
       }
 
-      if (!restored) {
-        const hash = router.history.location.hash.slice(1)
-
+      if (!windowRestored) {
         if (hash) {
-          const hashScrollIntoViewOptions =
-            window.history.state?.__hashScrollIntoViewOptions ?? true
-
           if (hashScrollIntoViewOptions) {
-            const el = document.getElementById(hash)
-            if (el) {
-              el.scrollIntoView(hashScrollIntoViewOptions)
-            }
+            document
+              .getElementById(hash)
+              ?.scrollIntoView(hashScrollIntoViewOptions)
           }
         } else {
           const scrollOptions = {
@@ -328,17 +362,11 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
             behavior,
           }
 
-          window.scrollTo(scrollOptions)
+          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)
-              }
+            scrollToTopElements ??= getScrollToTopElements(scrollToTopSelectors)
+            for (const element of scrollToTopElements) {
+              element.scrollTo(scrollOptions)
             }
           }
         }
@@ -346,12 +374,5 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
     } finally {
       ignoreScroll = false
     }
-
-    if (router.isScrollRestoring) {
-      cache.set((state) => {
-        state[cacheKey] ||= {} as ScrollRestorationByElement
-        return state
-      })
-    }
   })
 }

package/src/ssr/ssr-server.ts

@@ -292,23 +292,27 @@ export function attachRouterServerSsrUtils({
 }) {
   router.ssr = {
     get manifest() {
+      if (!manifest) return manifest
+
       const requestAssets = getRequestAssets?.()
-      const inlineCssAsset = getInlineCssAssetForMatches(
-        manifest,
-        router.stores.matches.get(),
-      )
-      if (!requestAssets?.length && !inlineCssAsset) return manifest
+      const matches = router.stores.matches.get()
+      const inlineCssAsset = getInlineCssAssetForMatches(manifest, matches)
+
+      if (!requestAssets?.length && !inlineCssAsset) {
+        return manifest
+      }
+
       // Merge request-scoped assets into root route without mutating cached manifest
       return {
         ...manifest,
         routes: {
-          ...manifest?.routes,
+          ...manifest.routes,
           [rootRouteId]: {
-            ...manifest?.routes?.[rootRouteId],
+            ...manifest.routes[rootRouteId],
             assets: [
               ...(requestAssets ?? []),
               ...(inlineCssAsset ? [inlineCssAsset] : []),
-              ...(manifest?.routes?.[rootRouteId]?.assets ?? []),
+              ...(manifest.routes[rootRouteId]?.assets ?? []),
             ],
           },
         },

package/dist/cjs/hash-scroll.cjs

@@ -1,20 +0,0 @@
-//#region src/hash-scroll.ts
-/**
-* @private
-* Handles hash-based scrolling after navigation completes.
-* To be used in framework-specific <Transitioner> components during the onResolved event.
-*/
-function handleHashScroll(router) {
-	if (typeof document !== "undefined" && document.querySelector) {
-		const location = router.stores.location.get();
-		const hashScrollIntoViewOptions = location.state.__hashScrollIntoViewOptions ?? true;
-		if (hashScrollIntoViewOptions && location.hash !== "") {
-			const el = document.getElementById(location.hash);
-			if (el) el.scrollIntoView(hashScrollIntoViewOptions);
-		}
-	}
-}
-//#endregion
-exports.handleHashScroll = handleHashScroll;
-
-//# sourceMappingURL=hash-scroll.cjs.map

package/dist/cjs/hash-scroll.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"hash-scroll.cjs","names":[],"sources":["../../src/hash-scroll.ts"],"sourcesContent":["import type { AnyRouter } from './router'\n\n/**\n * @private\n * Handles hash-based scrolling after navigation completes.\n * To be used in framework-specific <Transitioner> components during the onResolved event.\n */\nexport function handleHashScroll(router: AnyRouter) {\n  if (typeof document !== 'undefined' && (document as any).querySelector) {\n    const location = router.stores.location.get()\n    const hashScrollIntoViewOptions =\n      location.state.__hashScrollIntoViewOptions ?? true\n\n    if (hashScrollIntoViewOptions && location.hash !== '') {\n      const el = document.getElementById(location.hash)\n      if (el) {\n        el.scrollIntoView(hashScrollIntoViewOptions)\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;AAOA,SAAgB,iBAAiB,QAAmB;AAClD,KAAI,OAAO,aAAa,eAAgB,SAAiB,eAAe;EACtE,MAAM,WAAW,OAAO,OAAO,SAAS,KAAK;EAC7C,MAAM,4BACJ,SAAS,MAAM,+BAA+B;AAEhD,MAAI,6BAA6B,SAAS,SAAS,IAAI;GACrD,MAAM,KAAK,SAAS,eAAe,SAAS,KAAK;AACjD,OAAI,GACF,IAAG,eAAe,0BAA0B"}

package/dist/cjs/hash-scroll.d.cts

@@ -1,7 +0,0 @@
-import { AnyRouter } from './router.cjs';
-/**
- * @private
- * Handles hash-based scrolling after navigation completes.
- * To be used in framework-specific <Transitioner> components during the onResolved event.
- */
-export declare function handleHashScroll(router: AnyRouter): void;

package/dist/esm/hash-scroll.d.ts

@@ -1,7 +0,0 @@
-import { AnyRouter } from './router.js';
-/**
- * @private
- * Handles hash-based scrolling after navigation completes.
- * To be used in framework-specific <Transitioner> components during the onResolved event.
- */
-export declare function handleHashScroll(router: AnyRouter): void;

package/dist/esm/hash-scroll.js

@@ -1,20 +0,0 @@
-//#region src/hash-scroll.ts
-/**
-* @private
-* Handles hash-based scrolling after navigation completes.
-* To be used in framework-specific <Transitioner> components during the onResolved event.
-*/
-function handleHashScroll(router) {
-	if (typeof document !== "undefined" && document.querySelector) {
-		const location = router.stores.location.get();
-		const hashScrollIntoViewOptions = location.state.__hashScrollIntoViewOptions ?? true;
-		if (hashScrollIntoViewOptions && location.hash !== "") {
-			const el = document.getElementById(location.hash);
-			if (el) el.scrollIntoView(hashScrollIntoViewOptions);
-		}
-	}
-}
-//#endregion
-export { handleHashScroll };
-
-//# sourceMappingURL=hash-scroll.js.map

package/dist/esm/hash-scroll.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"hash-scroll.js","names":[],"sources":["../../src/hash-scroll.ts"],"sourcesContent":["import type { AnyRouter } from './router'\n\n/**\n * @private\n * Handles hash-based scrolling after navigation completes.\n * To be used in framework-specific <Transitioner> components during the onResolved event.\n */\nexport function handleHashScroll(router: AnyRouter) {\n  if (typeof document !== 'undefined' && (document as any).querySelector) {\n    const location = router.stores.location.get()\n    const hashScrollIntoViewOptions =\n      location.state.__hashScrollIntoViewOptions ?? true\n\n    if (hashScrollIntoViewOptions && location.hash !== '') {\n      const el = document.getElementById(location.hash)\n      if (el) {\n        el.scrollIntoView(hashScrollIntoViewOptions)\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;AAOA,SAAgB,iBAAiB,QAAmB;AAClD,KAAI,OAAO,aAAa,eAAgB,SAAiB,eAAe;EACtE,MAAM,WAAW,OAAO,OAAO,SAAS,KAAK;EAC7C,MAAM,4BACJ,SAAS,MAAM,+BAA+B;AAEhD,MAAI,6BAA6B,SAAS,SAAS,IAAI;GACrD,MAAM,KAAK,SAAS,eAAe,SAAS,KAAK;AACjD,OAAI,GACF,IAAG,eAAe,0BAA0B"}

package/src/hash-scroll.ts

@@ -1,21 +0,0 @@
-import type { AnyRouter } from './router'
-
-/**
- * @private
- * Handles hash-based scrolling after navigation completes.
- * To be used in framework-specific <Transitioner> components during the onResolved event.
- */
-export function handleHashScroll(router: AnyRouter) {
-  if (typeof document !== 'undefined' && (document as any).querySelector) {
-    const location = router.stores.location.get()
-    const hashScrollIntoViewOptions =
-      location.state.__hashScrollIntoViewOptions ?? true
-
-    if (hashScrollIntoViewOptions && location.hash !== '') {
-      const el = document.getElementById(location.hash)
-      if (el) {
-        el.scrollIntoView(hashScrollIntoViewOptions)
-      }
-    }
-  }
-}