@tanstack/router-core 1.168.4 → 1.168.6

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

@@ -1,26 +1,22 @@
 import { AnyRouter } from './router.cjs';
 import { ParsedLocation } from './location.cjs';
 import { NonNullableUpdater } from './utils.cjs';
-import { HistoryLocation } from '@tanstack/history';
 export type ScrollRestorationEntry = {
     scrollX: number;
     scrollY: number;
 };
-export type ScrollRestorationByElement = Record<string, ScrollRestorationEntry>;
-export type ScrollRestorationByKey = Record<string, ScrollRestorationByElement>;
-export type ScrollRestorationCache = {
-    state: ScrollRestorationByKey;
+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'];
 };
-/** 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. */
 export declare const storageKey = "tsr-scroll-restoration-v1_3";
-/** In-memory handle to the persisted scroll restoration cache. */
 export declare const scrollRestorationCache: ScrollRestorationCache | null;
 /**
  * The default `getKey` function for `useScrollRestoration`.
@@ -28,34 +24,15 @@ export declare const scrollRestorationCache: ScrollRestorationCache | null;
  *
  * 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 declare const defaultGetScrollRestorationKey: (location: ParsedLocation) => string;
-/** Best-effort nth-child CSS selector for a given element. */
-export declare function getCssSelector(el: any): string;
-export declare 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;
-}): void;
-/** Setup global listeners and hooks to support scroll restoration. */
-/** Setup global listeners and hooks to support scroll restoration. */
+export declare function getElementScrollRestorationEntry(router: AnyRouter, options: ({
+    id: string;
+    getElement?: () => Window | Element | undefined | null;
+} | {
+    id?: string;
+    getElement: () => Window | Element | undefined | null;
+}) & {
+    getKey?: (location: ParsedLocation) => string;
+}): ScrollRestorationEntry | undefined;
 export declare function setupScrollRestoration(router: AnyRouter, force?: boolean): void;
-/**
- * @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 declare function handleHashScroll(router: AnyRouter): void;
+export {};

package/dist/cjs/ssr/tsrScript.cjs

@@ -1,5 +1,5 @@
 //#region src/ssr/tsrScript.ts?script-string
-var tsrScript_default = "self.$_TSR={h(){this.hydrated=!0,this.c()},e(){this.streamEnded=!0,this.c()},c(){this.hydrated&&this.streamEnded&&(delete self.$_TSR,delete self.$R.tsr)},p(e){this.initialized?e():this.buffer.push(e)},buffer:[]};\n";
+var tsrScript_default = "self.$_TSR={h(){this.hydrated=!0,this.c()},e(){this.streamEnded=!0,this.c()},c(){this.hydrated&&this.streamEnded&&(delete self.$_TSR,delete self.$R.tsr)},p(e){this.initialized?e():this.buffer.push(e)},buffer:[]}";
 //#endregion
 exports.default = tsrScript_default;
 

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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,20 @@
+//#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.state;
+		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

@@ -0,0 +1 @@
+{"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.state\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;EACxC,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/esm/index.d.ts

@@ -40,7 +40,8 @@ export type { Redirect, RedirectOptions, RedirectOptionsRoute, RedirectFnRoute,
 export { redirect, isRedirect, isResolvedRedirect, parseRedirect, } from './redirect.js';
 export type { NotFoundError } from './not-found.js';
 export { isNotFound, notFound } from './not-found.js';
-export { defaultGetScrollRestorationKey, restoreScroll, storageKey, getCssSelector, scrollRestorationCache, setupScrollRestoration, handleHashScroll, } from './scroll-restoration.js';
+export { defaultGetScrollRestorationKey, getElementScrollRestorationEntry, storageKey, scrollRestorationCache, setupScrollRestoration, } from './scroll-restoration.js';
+export { handleHashScroll } from './hash-scroll.js';
 export type { ScrollRestorationOptions, ScrollRestorationEntry, } from './scroll-restoration.js';
 export type { ValidateFromPath, ValidateToPath, ValidateSearch, ValidateParams, InferFrom, InferTo, InferMaskTo, InferMaskFrom, ValidateNavigateOptions, ValidateNavigateOptionsArray, ValidateRedirectOptions, ValidateRedirectOptionsArray, ValidateId, InferStrict, InferShouldThrow, InferSelected, ValidateUseSearchResult, ValidateUseParamsResult, } from './typePrimitives.js';
 export type { AnySerializationAdapter, SerializationAdapter, ValidateSerializableInput, ValidateSerializableInputResult, SerializerExtensions, ValidateSerializable, RegisteredSerializableInput, SerializableExtensions, DefaultSerializable, Serializable, TSR_SERIALIZABLE, TsrSerializable, } from './ssr/serializer/transformer.js';

package/dist/esm/index.js

@@ -2,7 +2,7 @@ import { DEFAULT_PROTOCOL_ALLOWLIST, buildDevStylesUrl, createControlledPromise,
 import { invariant } from "./invariant.js";
 import { cleanPath, exactPathTest, interpolatePath, joinPaths, removeTrailingSlash, resolvePath, trimPath, trimPathLeft, trimPathRight } from "./path.js";
 import { isNotFound, notFound } from "./not-found.js";
-import { defaultGetScrollRestorationKey, getCssSelector, handleHashScroll, restoreScroll, scrollRestorationCache, setupScrollRestoration, storageKey } from "./scroll-restoration.js";
+import { defaultGetScrollRestorationKey, getElementScrollRestorationEntry, scrollRestorationCache, setupScrollRestoration, storageKey } from "./scroll-restoration.js";
 import { decode, encode } from "./qss.js";
 import { defaultParseSearch, defaultStringifySearch, parseSearchWith, stringifySearchWith } from "./searchParams.js";
 import { rootRouteId } from "./root.js";
@@ -17,7 +17,8 @@ import { isMatch } from "./Matches.js";
 import { BaseRootRoute, BaseRoute, BaseRouteApi } from "./route.js";
 import { createRouterConfig } from "./config.js";
 import { retainSearchParams, stripSearchParams } from "./searchMiddleware.js";
+import { handleHashScroll } from "./hash-scroll.js";
 import { createSerializationAdapter, makeSerovalPlugin, makeSsrSerovalPlugin } from "./ssr/serializer/transformer.js";
 import { RawStream, createRawStreamDeserializePlugin, createRawStreamRPCPlugin } from "./ssr/serializer/RawStream.js";
 import { defaultSerovalPlugins } from "./ssr/serializer/seroval-plugins.js";
-export { BaseRootRoute, BaseRoute, BaseRouteApi, DEFAULT_PROTOCOL_ALLOWLIST, PathParamError, RawStream, RouterCore, SearchParamError, TSR_DEFERRED_PROMISE, buildDevStylesUrl, cleanPath, composeRewrites, createControlledPromise, createNonReactiveMutableStore, createNonReactiveReadonlyStore, createRawStreamDeserializePlugin, createRawStreamRPCPlugin, createRouterConfig, createSerializationAdapter, decode, deepEqual, defaultGetScrollRestorationKey, defaultParseSearch, defaultSerializeError, defaultSerovalPlugins, defaultStringifySearch, defer, encode, escapeHtml, exactPathTest, executeRewriteInput, functionalUpdate, getAssetCrossOrigin, getCssSelector, getInitialRouterState, getLocationChangeInfo, getMatchedRoutes, handleHashScroll, interpolatePath, invariant, isDangerousProtocol, isMatch, isModuleNotFoundError, isNotFound, isPlainArray, isPlainObject, isRedirect, isResolvedRedirect, joinPaths, lazyFn, makeSerovalPlugin, makeSsrSerovalPlugin, notFound, parseRedirect, parseSearchWith, preloadWarning, redirect, removeTrailingSlash, replaceEqualDeep, resolveManifestAssetLink, resolvePath, restoreScroll, retainSearchParams, rootRouteId, scrollRestorationCache, setupScrollRestoration, storageKey, stringifySearchWith, stripSearchParams, trailingSlashOptions, trimPath, trimPathLeft, trimPathRight };
+export { BaseRootRoute, BaseRoute, BaseRouteApi, DEFAULT_PROTOCOL_ALLOWLIST, PathParamError, RawStream, RouterCore, SearchParamError, TSR_DEFERRED_PROMISE, buildDevStylesUrl, cleanPath, composeRewrites, createControlledPromise, createNonReactiveMutableStore, createNonReactiveReadonlyStore, createRawStreamDeserializePlugin, createRawStreamRPCPlugin, createRouterConfig, createSerializationAdapter, decode, deepEqual, defaultGetScrollRestorationKey, defaultParseSearch, defaultSerializeError, defaultSerovalPlugins, defaultStringifySearch, defer, encode, escapeHtml, exactPathTest, executeRewriteInput, functionalUpdate, getAssetCrossOrigin, getElementScrollRestorationEntry, getInitialRouterState, getLocationChangeInfo, getMatchedRoutes, handleHashScroll, interpolatePath, invariant, isDangerousProtocol, isMatch, isModuleNotFoundError, isNotFound, isPlainArray, isPlainObject, isRedirect, isResolvedRedirect, joinPaths, lazyFn, makeSerovalPlugin, makeSsrSerovalPlugin, notFound, parseRedirect, parseSearchWith, preloadWarning, redirect, removeTrailingSlash, replaceEqualDeep, resolveManifestAssetLink, resolvePath, retainSearchParams, rootRouteId, scrollRestorationCache, setupScrollRestoration, storageKey, stringifySearchWith, stripSearchParams, trailingSlashOptions, trimPath, trimPathLeft, trimPathRight };

package/dist/esm/scroll-restoration-inline.d.ts

@@ -0,0 +1,6 @@
+export default function (options: {
+    storageKey: string;
+    key?: string;
+    behavior?: ScrollToOptions['behavior'];
+    shouldScrollRestoration?: boolean;
+}): void;

package/dist/esm/scroll-restoration-inline.js

@@ -0,0 +1,6 @@
+//#region src/scroll-restoration-inline.ts?script-string
+var scroll_restoration_inline_default = "function(t){let s;try{s=JSON.parse(sessionStorage.getItem(t.storageKey)||\"{}\")}catch(e){console.error(e);return}const c=t.key||window.history.state?.__TSR_key,r=c?s[c]:void 0;if(t.shouldScrollRestoration&&r&&typeof r==\"object\"&&Object.keys(r).length>0){for(const e in r){const o=r[e];if(!o||typeof o!=\"object\")continue;const l=o.scrollX,i=o.scrollY;if(!(!Number.isFinite(l)||!Number.isFinite(i))){if(e===\"window\")window.scrollTo({top:i,left:l,behavior:t.behavior});else if(e){let n;try{n=document.querySelector(e)}catch{continue}n&&(n.scrollLeft=l,n.scrollTop=i)}}}return}const a=window.location.hash.split(\"#\",2)[1];if(a){const e=window.history.state?.__hashScrollIntoViewOptions??!0;if(e){const o=document.getElementById(a);o&&o.scrollIntoView(e)}return}window.scrollTo({top:0,left:0,behavior:t.behavior})}";
+//#endregion
+export { scroll_restoration_inline_default as default };
+
+//# sourceMappingURL=scroll-restoration-inline.js.map

package/dist/esm/scroll-restoration-inline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-restoration-inline.js","names":[],"sources":["../../src/scroll-restoration-inline.ts?script-string"],"sourcesContent":["export default function (options: {\n  storageKey: string\n  key?: string\n  behavior?: ScrollToOptions['behavior']\n  shouldScrollRestoration?: boolean\n}) {\n  let byKey\n\n  try {\n    byKey = JSON.parse(sessionStorage.getItem(options.storageKey) || '{}')\n  } catch (error) {\n    console.error(error)\n    return\n  }\n\n  const resolvedKey = options.key || window.history.state?.__TSR_key\n  const elementEntries = resolvedKey ? byKey[resolvedKey] : undefined\n\n  if (\n    options.shouldScrollRestoration &&\n    elementEntries &&\n    typeof elementEntries === 'object' &&\n    Object.keys(elementEntries).length > 0\n  ) {\n    for (const elementSelector in elementEntries) {\n      const entry = elementEntries[elementSelector]\n\n      if (!entry || typeof entry !== 'object') {\n        continue\n      }\n\n      const scrollX = entry.scrollX\n      const scrollY = entry.scrollY\n\n      if (!Number.isFinite(scrollX) || !Number.isFinite(scrollY)) {\n        continue\n      }\n\n      if (elementSelector === 'window') {\n        window.scrollTo({\n          top: scrollY,\n          left: scrollX,\n          behavior: options.behavior,\n        })\n      } else if (elementSelector) {\n        let element\n\n        try {\n          element = document.querySelector(elementSelector)\n        } catch {\n          continue\n        }\n\n        if (element) {\n          element.scrollLeft = scrollX\n          element.scrollTop = scrollY\n        }\n      }\n    }\n\n    return\n  }\n\n  const hash = window.location.hash.split('#', 2)[1]\n\n  if (hash) {\n    const hashScrollIntoViewOptions =\n      window.history.state?.__hashScrollIntoViewOptions ?? true\n\n    if (hashScrollIntoViewOptions) {\n      const el = document.getElementById(hash)\n      if (el) {\n        el.scrollIntoView(hashScrollIntoViewOptions)\n      }\n    }\n\n    return\n  }\n\n  window.scrollTo({ top: 0, left: 0, behavior: options.behavior })\n}\n"],"mappings":";AAAA,IAAA,oCAAe"}

package/dist/esm/scroll-restoration-script/client.d.ts

@@ -0,0 +1,2 @@
+import { AnyRouter } from '../router.js';
+export declare function getScrollRestorationScriptForRouter(_router: AnyRouter): null;

package/dist/esm/scroll-restoration-script/client.js

@@ -0,0 +1,8 @@
+//#region src/scroll-restoration-script/client.ts
+function getScrollRestorationScriptForRouter(_router) {
+	return null;
+}
+//#endregion
+export { getScrollRestorationScriptForRouter };
+
+//# sourceMappingURL=client.js.map

package/dist/esm/scroll-restoration-script/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../../../src/scroll-restoration-script/client.ts"],"sourcesContent":["import type { AnyRouter } from '../router'\n\nexport function getScrollRestorationScriptForRouter(_router: AnyRouter) {\n  return null\n}\n"],"mappings":";AAEA,SAAgB,oCAAoC,SAAoB;AACtE,QAAO"}

package/dist/esm/scroll-restoration-script/server.d.ts

@@ -0,0 +1,2 @@
+import { AnyRouter } from '../router.js';
+export declare function getScrollRestorationScriptForRouter(router: AnyRouter): string | null;

package/dist/esm/scroll-restoration-script/server.js

@@ -0,0 +1,29 @@
+import { escapeHtml } from "../utils.js";
+import { defaultGetScrollRestorationKey, storageKey } from "../scroll-restoration.js";
+import scroll_restoration_inline_default from "../scroll-restoration-inline.js";
+//#region src/scroll-restoration-script/server.ts
+var defaultInlineScrollRestorationScript = `(${scroll_restoration_inline_default})(${escapeHtml(JSON.stringify({
+	storageKey,
+	shouldScrollRestoration: true
+}))})`;
+function getScrollRestorationScript(options) {
+	if (options.storageKey === "tsr-scroll-restoration-v1_3" && options.shouldScrollRestoration === true && options.key === void 0 && options.behavior === void 0) return defaultInlineScrollRestorationScript;
+	return `(${scroll_restoration_inline_default})(${escapeHtml(JSON.stringify(options))})`;
+}
+function getScrollRestorationScriptForRouter(router) {
+	if (typeof router.options.scrollRestoration === "function" && !router.options.scrollRestoration({ location: router.latestLocation })) return null;
+	const getKey = router.options.getScrollRestorationKey;
+	if (!getKey) return defaultInlineScrollRestorationScript;
+	const location = router.latestLocation;
+	const userKey = getKey(location);
+	if (userKey === defaultGetScrollRestorationKey(location)) return defaultInlineScrollRestorationScript;
+	return getScrollRestorationScript({
+		storageKey,
+		shouldScrollRestoration: true,
+		key: userKey
+	});
+}
+//#endregion
+export { getScrollRestorationScriptForRouter };
+
+//# sourceMappingURL=server.js.map

package/dist/esm/scroll-restoration-script/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","names":[],"sources":["../../../src/scroll-restoration-script/server.ts"],"sourcesContent":["import minifiedScrollRestorationScript from '../scroll-restoration-inline?script-string'\nimport {\n  defaultGetScrollRestorationKey,\n  storageKey,\n} from '../scroll-restoration'\nimport { escapeHtml } from '../utils'\nimport type { AnyRouter } from '../router'\n\ntype InlineScrollRestorationScriptOptions = {\n  storageKey: string\n  key?: string\n  behavior?: ScrollToOptions['behavior']\n  shouldScrollRestoration?: boolean\n}\n\nconst defaultInlineScrollRestorationScript = `(${minifiedScrollRestorationScript})(${escapeHtml(\n  JSON.stringify({\n    storageKey,\n    shouldScrollRestoration: true,\n  } satisfies InlineScrollRestorationScriptOptions),\n)})`\n\nfunction getScrollRestorationScript(\n  options: InlineScrollRestorationScriptOptions,\n) {\n  if (\n    options.storageKey === storageKey &&\n    options.shouldScrollRestoration === true &&\n    options.key === undefined &&\n    options.behavior === undefined\n  ) {\n    return defaultInlineScrollRestorationScript\n  }\n\n  return `(${minifiedScrollRestorationScript})(${escapeHtml(JSON.stringify(options))})`\n}\n\nexport function getScrollRestorationScriptForRouter(router: AnyRouter) {\n  if (\n    typeof router.options.scrollRestoration === 'function' &&\n    !router.options.scrollRestoration({ location: router.latestLocation })\n  ) {\n    return null\n  }\n\n  const getKey = router.options.getScrollRestorationKey\n  if (!getKey) {\n    return defaultInlineScrollRestorationScript\n  }\n\n  const location = router.latestLocation\n  const userKey = getKey(location)\n  const defaultKey = defaultGetScrollRestorationKey(location)\n\n  if (userKey === defaultKey) {\n    return defaultInlineScrollRestorationScript\n  }\n\n  return getScrollRestorationScript({\n    storageKey,\n    shouldScrollRestoration: true,\n    key: userKey,\n  })\n}\n"],"mappings":";;;;AAeA,IAAM,uCAAuC,IAAI,kCAAgC,IAAI,WACnF,KAAK,UAAU;CACb;CACA,yBAAyB;CAC1B,CAAgD,CAClD,CAAC;AAEF,SAAS,2BACP,SACA;AACA,KACE,QAAQ,eAAA,iCACR,QAAQ,4BAA4B,QACpC,QAAQ,QAAQ,KAAA,KAChB,QAAQ,aAAa,KAAA,EAErB,QAAO;AAGT,QAAO,IAAI,kCAAgC,IAAI,WAAW,KAAK,UAAU,QAAQ,CAAC,CAAC;;AAGrF,SAAgB,oCAAoC,QAAmB;AACrE,KACE,OAAO,OAAO,QAAQ,sBAAsB,cAC5C,CAAC,OAAO,QAAQ,kBAAkB,EAAE,UAAU,OAAO,gBAAgB,CAAC,CAEtE,QAAO;CAGT,MAAM,SAAS,OAAO,QAAQ;AAC9B,KAAI,CAAC,OACH,QAAO;CAGT,MAAM,WAAW,OAAO;CACxB,MAAM,UAAU,OAAO,SAAS;AAGhC,KAAI,YAFe,+BAA+B,SAAS,CAGzD,QAAO;AAGT,QAAO,2BAA2B;EAChC;EACA,yBAAyB;EACzB,KAAK;EACN,CAAC"}

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

@@ -1,26 +1,22 @@
 import { AnyRouter } from './router.js';
 import { ParsedLocation } from './location.js';
 import { NonNullableUpdater } from './utils.js';
-import { HistoryLocation } from '@tanstack/history';
 export type ScrollRestorationEntry = {
     scrollX: number;
     scrollY: number;
 };
-export type ScrollRestorationByElement = Record<string, ScrollRestorationEntry>;
-export type ScrollRestorationByKey = Record<string, ScrollRestorationByElement>;
-export type ScrollRestorationCache = {
-    state: ScrollRestorationByKey;
+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'];
 };
-/** 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. */
 export declare const storageKey = "tsr-scroll-restoration-v1_3";
-/** In-memory handle to the persisted scroll restoration cache. */
 export declare const scrollRestorationCache: ScrollRestorationCache | null;
 /**
  * The default `getKey` function for `useScrollRestoration`.
@@ -28,34 +24,15 @@ export declare const scrollRestorationCache: ScrollRestorationCache | null;
  *
  * 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 declare const defaultGetScrollRestorationKey: (location: ParsedLocation) => string;
-/** Best-effort nth-child CSS selector for a given element. */
-export declare function getCssSelector(el: any): string;
-export declare 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;
-}): void;
-/** Setup global listeners and hooks to support scroll restoration. */
-/** Setup global listeners and hooks to support scroll restoration. */
+export declare function getElementScrollRestorationEntry(router: AnyRouter, options: ({
+    id: string;
+    getElement?: () => Window | Element | undefined | null;
+} | {
+    id?: string;
+    getElement: () => Window | Element | undefined | null;
+}) & {
+    getKey?: (location: ParsedLocation) => string;
+}): ScrollRestorationEntry | undefined;
 export declare function setupScrollRestoration(router: AnyRouter, force?: boolean): void;
-/**
- * @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 declare function handleHashScroll(router: AnyRouter): void;
+export {};

package/dist/esm/scroll-restoration.js

@@ -1,42 +1,39 @@
-import { functionalUpdate } from "./utils.js";
+import { functionalUpdate, isPlainObject } from "./utils.js";
 import { isServer } from "@tanstack/router-core/isServer";
 //#region src/scroll-restoration.ts
 function getSafeSessionStorage() {
 	try {
-		if (typeof window !== "undefined" && typeof window.sessionStorage === "object") return window.sessionStorage;
-	} catch {}
+		return typeof window !== "undefined" && typeof window.sessionStorage === "object" ? window.sessionStorage : void 0;
+	} catch {
+		return;
+	}
 }
-/** 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. */
 var storageKey = "tsr-scroll-restoration-v1_3";
-var throttle = (fn, wait) => {
-	let timeout;
-	return (...args) => {
-		if (!timeout) timeout = setTimeout(() => {
-			fn(...args);
-			timeout = null;
-		}, wait);
-	};
-};
 function createScrollRestorationCache() {
 	const safeSessionStorage = getSafeSessionStorage();
 	if (!safeSessionStorage) return null;
-	const persistedState = safeSessionStorage.getItem(storageKey);
-	let state = persistedState ? JSON.parse(persistedState) : {};
+	let state = {};
+	try {
+		const parsed = JSON.parse(safeSessionStorage.getItem("tsr-scroll-restoration-v1_3") || "{}");
+		if (isPlainObject(parsed)) state = parsed;
+	} catch {}
+	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 {
-		state,
+		get state() {
+			return state;
+		},
 		set: (updater) => {
 			state = functionalUpdate(updater, state) || state;
-			try {
-				safeSessionStorage.setItem(storageKey, JSON.stringify(state));
-			} catch {
-				console.warn("[ts-router] Could not persist scroll restoration state to sessionStorage.");
-			}
-		}
+		},
+		persist
 	};
 }
-/** In-memory handle to the persisted scroll restoration cache. */
 var scrollRestorationCache = createScrollRestorationCache();
 /**
 * The default `getKey` function for `useScrollRestoration`.
@@ -44,13 +41,9 @@ var 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.
-*/
 var defaultGetScrollRestorationKey = (location) => {
 	return location.state.__TSR_key || location.href;
 };
-/** Best-effort nth-child CSS selector for a given element. */
 function getCssSelector(el) {
 	const path = [];
 	let parent;
@@ -60,144 +53,135 @@ function getCssSelector(el) {
 	}
 	return `${path.reverse().join(" > ")}`.toLowerCase();
 }
-var ignoreScroll = false;
-function restoreScroll({ storageKey, key, behavior, shouldScrollRestoration, scrollToTopSelectors, location }) {
-	let byKey;
-	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 (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;
-					}
-				}
-			}
-			break scroll;
-		}
-		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);
-			}
-			break scroll;
-		}
-		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);
-		}
-	}
-	ignoreScroll = false;
+function getElementScrollRestorationEntry(router, options) {
+	const restoreKey = (options.getKey || defaultGetScrollRestorationKey)(router.latestLocation);
+	if (options.id) return scrollRestorationCache?.state[restoreKey]?.[`[${scrollRestorationIdAttribute}="${options.id}"]`];
+	const element = options.getElement?.();
+	if (!element) return;
+	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. */
+var ignoreScroll = false;
+var windowScrollTarget = "window";
+var scrollRestorationIdAttribute = "data-scroll-restoration-id";
 function setupScrollRestoration(router, force) {
 	if (!scrollRestorationCache && !(isServer ?? router.isServer)) return;
+	const cache = scrollRestorationCache;
 	if (force ?? router.options.scrollRestoration ?? false) router.isScrollRestoring = true;
-	if ((isServer ?? router.isServer) || router.isScrollRestorationSetup || !scrollRestorationCache) return;
+	if ((isServer ?? router.isServer) || router.isScrollRestorationSetup || !cache) return;
 	router.isScrollRestorationSetup = true;
 	ignoreScroll = false;
 	const getKey = router.options.getScrollRestorationKey || defaultGetScrollRestorationKey;
+	const trackedScrollEntries = /* @__PURE__ */ new Map();
 	window.history.scrollRestoration = "manual";
 	const onScroll = (event) => {
 		if (ignoreScroll || !router.isScrollRestoring) return;
-		let elementSelector = "";
-		if (event.target === document || event.target === window) elementSelector = "window";
+		if (event.target === document || event.target === window) trackedScrollEntries.set(windowScrollTarget, {
+			scrollX: window.scrollX || 0,
+			scrollY: window.scrollY || 0
+		});
 		else {
-			const attrId = event.target.getAttribute("data-scroll-restoration-id");
-			if (attrId) elementSelector = `[data-scroll-restoration-id="${attrId}"]`;
-			else elementSelector = getCssSelector(event.target);
+			const target = event.target;
+			trackedScrollEntries.set(target, {
+				scrollX: target.scrollLeft || 0,
+				scrollY: target.scrollTop || 0
+			});
 		}
-		const restoreKey = getKey(router.stores.location.state);
-		scrollRestorationCache.set((state) => {
-			const keyEntry = state[restoreKey] ||= {};
-			const elementEntry = keyEntry[elementSelector] ||= {};
-			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;
-				}
+	};
+	const snapshotCurrentScrollTargets = (restoreKey) => {
+		if (!router.isScrollRestoring || !restoreKey || trackedScrollEntries.size === 0 || !cache) return;
+		const keyEntry = cache.state[restoreKey] ||= {};
+		for (const [target, position] of trackedScrollEntries) {
+			let selector;
+			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;
+			keyEntry[selector] = position;
+		}
 	};
-	if (typeof document !== "undefined") document.addEventListener("scroll", throttle(onScroll, 100), true);
+	document.addEventListener("scroll", onScroll, true);
+	router.subscribe("onBeforeLoad", (event) => {
+		snapshotCurrentScrollTargets(event.fromLocation ? getKey(event.fromLocation) : void 0);
+		trackedScrollEntries.clear();
+	});
+	window.addEventListener("pagehide", () => {
+		snapshotCurrentScrollTargets(getKey(router.stores.resolvedLocation.state ?? router.stores.location.state));
+		cache.persist();
+	});
 	router.subscribe("onRendered", (event) => {
 		const cacheKey = getKey(event.toLocation);
+		const behavior = router.options.scrollRestorationBehavior;
+		const scrollToTopSelectors = router.options.scrollToTopSelectors;
+		trackedScrollEntries.clear();
 		if (!router.resetNextScroll) {
 			router.resetNextScroll = true;
 			return;
 		}
-		if (typeof router.options.scrollRestoration === "function") {
-			if (!router.options.scrollRestoration({ location: router.latestLocation })) return;
+		if (typeof router.options.scrollRestoration === "function" && !router.options.scrollRestoration({ location: router.latestLocation })) return;
+		ignoreScroll = true;
+		try {
+			const elementEntries = router.isScrollRestoring ? cache.state[cacheKey] : void 0;
+			let restored = false;
+			if (elementEntries) for (const elementSelector in elementEntries) {
+				const entry = elementEntries[elementSelector];
+				if (!isPlainObject(entry)) continue;
+				const { scrollX, scrollY } = entry;
+				if (!Number.isFinite(scrollX) || !Number.isFinite(scrollY)) continue;
+				if (elementSelector === windowScrollTarget) {
+					window.scrollTo({
+						top: scrollY,
+						left: scrollX,
+						behavior
+					});
+					restored = true;
+				} else if (elementSelector) {
+					let element;
+					try {
+						element = document.querySelector(elementSelector);
+					} catch {
+						continue;
+					}
+					if (element) {
+						element.scrollLeft = scrollX;
+						element.scrollTop = scrollY;
+						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;
 		}
-		restoreScroll({
-			storageKey,
-			key: cacheKey,
-			behavior: router.options.scrollRestorationBehavior,
-			shouldScrollRestoration: router.isScrollRestoring,
-			scrollToTopSelectors: router.options.scrollToTopSelectors,
-			location: router.history.location
-		});
-		if (router.isScrollRestoring) scrollRestorationCache.set((state) => {
+		if (router.isScrollRestoring) cache.set((state) => {
 			state[cacheKey] ||= {};
 			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.
-*/
-function handleHashScroll(router) {
-	if (typeof document !== "undefined" && document.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);
-		}
-	}
-}
 //#endregion
-export { defaultGetScrollRestorationKey, getCssSelector, handleHashScroll, restoreScroll, scrollRestorationCache, setupScrollRestoration, storageKey };
+export { defaultGetScrollRestorationKey, getElementScrollRestorationEntry, scrollRestorationCache, setupScrollRestoration, storageKey };
 
 //# sourceMappingURL=scroll-restoration.js.map