@tanstack/router-core 1.114.12 → 1.114.16

package/dist/cjs/index.cjs

@@ -12,6 +12,7 @@ const searchParams = require("./searchParams.cjs");
 const utils = require("./utils.cjs");
 const redirect = require("./redirect.cjs");
 const notFound = require("./not-found.cjs");
+const scrollRestoration = require("./scroll-restoration.cjs");
 exports.TSR_DEFERRED_PROMISE = defer.TSR_DEFERRED_PROMISE;
 exports.defer = defer.defer;
 exports.preloadWarning = link.preloadWarning;
@@ -55,4 +56,10 @@ exports.isResolvedRedirect = redirect.isResolvedRedirect;
 exports.redirect = redirect.redirect;
 exports.isNotFound = notFound.isNotFound;
 exports.notFound = notFound.notFound;
+exports.defaultGetScrollRestorationKey = scrollRestoration.defaultGetScrollRestorationKey;
+exports.getCssSelector = scrollRestoration.getCssSelector;
+exports.restoreScroll = scrollRestoration.restoreScroll;
+exports.scrollRestorationCache = scrollRestoration.scrollRestorationCache;
+exports.setupScrollRestoration = scrollRestoration.setupScrollRestoration;
+exports.storageKey = scrollRestoration.storageKey;
 //# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/index.d.cts

@@ -35,3 +35,6 @@ export type { Redirect, ResolvedRedirect, AnyRedirect } from './redirect.cjs';
 export { redirect, isRedirect, isResolvedRedirect } from './redirect.cjs';
 export type { NotFoundError } from './not-found.cjs';
 export { isNotFound, notFound } from './not-found.cjs';
+export { defaultGetScrollRestorationKey, restoreScroll, storageKey, getCssSelector, scrollRestorationCache, setupScrollRestoration, } from './scroll-restoration.cjs';
+export type { ScrollRestorationOptions, ScrollRestorationEntry, } from './scroll-restoration.cjs';
+export type { ValidateFromPath, ValidateToPath, ValidateSearch, ValidateParams, InferFrom, InferTo, InferMaskTo, InferMaskFrom, ValidateNavigateOptions, ValidateNavigateOptionsArray, ValidateRedirectOptions, ValidateRedirectOptionsArray, ValidateId, InferStrict, InferShouldThrow, InferSelected, ValidateUseSearchResult, ValidateUseParamsResult, } from './typePrimitives.cjs';

package/dist/cjs/scroll-restoration.cjs

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("./utils.cjs");
+const storageKey = "tsr-scroll-restoration-v1_3";
+let sessionsStorage = false;
+try {
+  sessionsStorage = typeof window !== "undefined" && typeof window.sessionStorage === "object";
+} catch {
+}
+const throttle = (fn, wait) => {
+  let timeout;
+  return (...args) => {
+    if (!timeout) {
+      timeout = setTimeout(() => {
+        fn(...args);
+        timeout = null;
+      }, wait);
+    }
+  };
+};
+const scrollRestorationCache = sessionsStorage ? (() => {
+  const state = JSON.parse(window.sessionStorage.getItem(storageKey) || "null") || {};
+  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) => (scrollRestorationCache.state = utils.functionalUpdate(updater, scrollRestorationCache.state) || scrollRestorationCache.state, window.sessionStorage.setItem(
+      storageKey,
+      JSON.stringify(scrollRestorationCache.state)
+    ))
+  };
+})() : void 0;
+const defaultGetScrollRestorationKey = (location) => {
+  return location.state.key || location.href;
+};
+function getCssSelector(el) {
+  const path = [];
+  let parent;
+  while (parent = el.parentNode) {
+    path.unshift(
+      `${el.tagName}:nth-child(${[].indexOf.call(parent.children, el) + 1})`
+    );
+    el = parent;
+  }
+  return `${path.join(" > ")}`.toLowerCase();
+}
+let ignoreScroll = false;
+function restoreScroll(storageKey2, key, behavior, shouldScrollRestoration, scrollToTopSelectors) {
+  var _a;
+  let byKey;
+  try {
+    byKey = JSON.parse(sessionStorage.getItem(storageKey2) || "{}");
+  } catch (error) {
+    console.error(error);
+    return;
+  }
+  const resolvedKey = key || ((_a = window.history.state) == null ? void 0 : _a.key);
+  const elementEntries = byKey[resolvedKey];
+  ignoreScroll = true;
+  (() => {
+    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;
+          }
+        }
+      }
+      return;
+    }
+    const hash = window.location.hash.split("#")[1];
+    if (hash) {
+      const hashScrollIntoViewOptions = (window.history.state || {}).__hashScrollIntoViewOptions ?? true;
+      if (hashScrollIntoViewOptions) {
+        const el = document.getElementById(hash);
+        if (el) {
+          el.scrollIntoView(hashScrollIntoViewOptions);
+        }
+      }
+      return;
+    }
+    [
+      "window",
+      ...(scrollToTopSelectors == null ? void 0 : scrollToTopSelectors.filter((d) => d !== "window")) ?? []
+    ].forEach((selector) => {
+      const element = selector === "window" ? window : document.querySelector(selector);
+      if (element) {
+        element.scrollTo({
+          top: 0,
+          left: 0,
+          behavior
+        });
+      }
+    });
+  })();
+  ignoreScroll = false;
+}
+function setupScrollRestoration(router, force) {
+  const shouldScrollRestoration = force ?? router.options.scrollRestoration ?? false;
+  if (shouldScrollRestoration) {
+    router.isScrollRestoring = true;
+  }
+  if (typeof document === "undefined" || router.isScrollRestorationSetup) {
+    return;
+  }
+  router.isScrollRestorationSetup = true;
+  ignoreScroll = false;
+  const getKey = router.options.getScrollRestorationKey || defaultGetScrollRestorationKey;
+  window.history.scrollRestoration = "manual";
+  const onScroll = (event) => {
+    if (ignoreScroll || !router.isScrollRestoring) {
+      return;
+    }
+    let elementSelector = "";
+    if (event.target === document || event.target === window) {
+      elementSelector = "window";
+    } else {
+      const attrId = event.target.getAttribute(
+        "data-scroll-restoration-id"
+      );
+      if (attrId) {
+        elementSelector = `[data-scroll-restoration-id="${attrId}"]`;
+      } else {
+        elementSelector = getCssSelector(event.target);
+      }
+    }
+    const restoreKey = getKey(router.state.location);
+    scrollRestorationCache.set((state) => {
+      const keyEntry = state[restoreKey] = state[restoreKey] || {};
+      const elementEntry = keyEntry[elementSelector] = 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;
+        }
+      }
+      return state;
+    });
+  };
+  if (typeof document !== "undefined") {
+    document.addEventListener("scroll", throttle(onScroll, 100), true);
+  }
+  router.subscribe("onRendered", (event) => {
+    const cacheKey = getKey(event.toLocation);
+    if (!router.resetNextScroll) {
+      router.resetNextScroll = true;
+      return;
+    }
+    restoreScroll(
+      storageKey,
+      cacheKey,
+      router.options.scrollRestorationBehavior || void 0,
+      router.isScrollRestoring || void 0,
+      router.options.scrollToTopSelectors || void 0
+    );
+    if (router.isScrollRestoring) {
+      scrollRestorationCache.set((state) => {
+        state[cacheKey] = state[cacheKey] || {};
+        return state;
+      });
+    }
+  });
+}
+exports.defaultGetScrollRestorationKey = defaultGetScrollRestorationKey;
+exports.getCssSelector = getCssSelector;
+exports.restoreScroll = restoreScroll;
+exports.scrollRestorationCache = scrollRestorationCache;
+exports.setupScrollRestoration = setupScrollRestoration;
+exports.storageKey = storageKey;
+//# sourceMappingURL=scroll-restoration.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-restoration.cjs","sources":["../../src/scroll-restoration.ts"],"sourcesContent":["import { functionalUpdate } from './utils'\nimport type { AnyRouter } from './router'\nimport type { ParsedLocation } from './location'\nimport type { NonNullableUpdater } from './utils'\n\nexport type ScrollRestorationEntry = { scrollX: number; scrollY: number }\n\nexport type ScrollRestorationByElement = Record<string, ScrollRestorationEntry>\n\nexport type ScrollRestorationByKey = Record<string, ScrollRestorationByElement>\n\nexport type ScrollRestorationCache = {\n  state: ScrollRestorationByKey\n  set: (updater: NonNullableUpdater<ScrollRestorationByKey>) => void\n}\nexport type ScrollRestorationOptions = {\n  getKey?: (location: ParsedLocation) => string\n  scrollBehavior?: ScrollToOptions['behavior']\n}\n\nexport const storageKey = 'tsr-scroll-restoration-v1_3'\nlet sessionsStorage = false\ntry {\n  sessionsStorage =\n    typeof window !== 'undefined' && typeof window.sessionStorage === 'object'\n} catch {}\nconst throttle = (fn: (...args: Array<any>) => void, wait: number) => {\n  let timeout: any\n  return (...args: Array<any>) => {\n    if (!timeout) {\n      timeout = setTimeout(() => {\n        fn(...args)\n        timeout = null\n      }, wait)\n    }\n  }\n}\nexport const scrollRestorationCache: ScrollRestorationCache = sessionsStorage\n  ? (() => {\n      const state: ScrollRestorationByKey =\n        JSON.parse(window.sessionStorage.getItem(storageKey) || 'null') || {}\n\n      return {\n        state,\n        // This setter is simply to make sure that we set the sessionStorage right\n        // after the state is updated. It doesn't necessarily need to be a functional\n        // update.\n        set: (updater) => (\n          (scrollRestorationCache.state =\n            functionalUpdate(updater, scrollRestorationCache.state) ||\n            scrollRestorationCache.state),\n          window.sessionStorage.setItem(\n            storageKey,\n            JSON.stringify(scrollRestorationCache.state),\n          )\n        ),\n      }\n    })()\n  : (undefined as any)\n/**\n * The default `getKey` function for `useScrollRestoration`.\n * It returns the `key` from the location state or the `href` of the location.\n *\n * The `location.href` is used as a fallback to support the use case where the location state is not available like the initial render.\n */\n\nexport const defaultGetScrollRestorationKey = (location: ParsedLocation) => {\n  return location.state.key! || location.href\n}\n\nexport function getCssSelector(el: any): string {\n  const path = []\n  let parent\n  while ((parent = el.parentNode)) {\n    path.unshift(\n      `${el.tagName}:nth-child(${([].indexOf as any).call(parent.children, el) + 1})`,\n    )\n    el = parent\n  }\n  return `${path.join(' > ')}`.toLowerCase()\n}\n\nlet ignoreScroll = false\n\n// NOTE: This function must remain pure and not use any outside variables\n// unless they are passed in as arguments. Why? Because we need to be able to\n// toString() it into a script tag to execute as early as possible in the browser\n// during SSR. Additionally, we also call it from within the router lifecycle\nexport function restoreScroll(\n  storageKey: string,\n  key: string | undefined,\n  behavior: ScrollToOptions['behavior'] | undefined,\n  shouldScrollRestoration: boolean | undefined,\n  scrollToTopSelectors: Array<string> | undefined,\n) {\n  let byKey: ScrollRestorationByKey\n\n  try {\n    byKey = JSON.parse(sessionStorage.getItem(storageKey) || '{}')\n  } catch (error: any) {\n    console.error(error)\n    return\n  }\n\n  const resolvedKey = key || window.history.state?.key\n  const elementEntries = byKey[resolvedKey]\n\n  //\n  ignoreScroll = true\n\n  //\n  ;(() => {\n    // If we have a cached entry for this location state,\n    // we always need to prefer that over the hash scroll.\n    if (shouldScrollRestoration && elementEntries) {\n      for (const elementSelector in elementEntries) {\n        const entry = elementEntries[elementSelector]!\n        if (elementSelector === 'window') {\n          window.scrollTo({\n            top: entry.scrollY,\n            left: entry.scrollX,\n            behavior,\n          })\n        } else if (elementSelector) {\n          const element = document.querySelector(elementSelector)\n          if (element) {\n            element.scrollLeft = entry.scrollX\n            element.scrollTop = entry.scrollY\n          }\n        }\n      }\n\n      return\n    }\n\n    // If we don't have a cached entry for the hash,\n    // Which means we've never seen this location before,\n    // we need to check if there is a hash in the URL.\n    // If there is, we need to scroll it's ID into view.\n    const hash = window.location.hash.split('#')[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    // If there is no cached entry for the hash and there is no hash in the URL,\n    // we need to scroll to the top of the page for every scrollToTop element\n    ;[\n      'window',\n      ...(scrollToTopSelectors?.filter((d) => d !== 'window') ?? []),\n    ].forEach((selector) => {\n      const element =\n        selector === 'window' ? window : document.querySelector(selector)\n      if (element) {\n        element.scrollTo({\n          top: 0,\n          left: 0,\n          behavior,\n        })\n      }\n    })\n  })()\n\n  //\n  ignoreScroll = false\n}\n\nexport function setupScrollRestoration(router: AnyRouter, force?: boolean) {\n  const shouldScrollRestoration =\n    force ?? router.options.scrollRestoration ?? false\n\n  if (shouldScrollRestoration) {\n    router.isScrollRestoring = true\n  }\n\n  if (typeof document === 'undefined' || router.isScrollRestorationSetup) {\n    return\n  }\n\n  router.isScrollRestorationSetup = true\n\n  //\n  ignoreScroll = false\n\n  const getKey =\n    router.options.getScrollRestorationKey || defaultGetScrollRestorationKey\n\n  window.history.scrollRestoration = 'manual'\n\n  // // Create a MutationObserver to monitor DOM changes\n  // const mutationObserver = new MutationObserver(() => {\n  //   ;ignoreScroll = true\n  //   requestAnimationFrame(() => {\n  //     ;ignoreScroll = false\n\n  //     // Attempt to restore scroll position on each dom\n  //     // mutation until the user scrolls. We do this\n  //     // because dynamic content may come in at different\n  //     // ticks after the initial render and we want to\n  //     // keep up with that content as much as possible.\n  //     // As soon as the user scrolls, we no longer need\n  //     // to attempt router.\n  //     // console.log('mutation observer restoreScroll')\n  //     restoreScroll(\n  //       storageKey,\n  //       getKey(router.state.location),\n  //       router.options.scrollRestorationBehavior,\n  //     )\n  //   })\n  // })\n\n  // const observeDom = () => {\n  //   // Observe changes to the entire document\n  //   mutationObserver.observe(document, {\n  //     childList: true, // Detect added or removed child nodes\n  //     subtree: true, // Monitor all descendants\n  //     characterData: true, // Detect text content changes\n  //   })\n  // }\n\n  // const unobserveDom = () => {\n  //   mutationObserver.disconnect()\n  // }\n\n  // observeDom()\n\n  const onScroll = (event: Event) => {\n    // unobserveDom()\n\n    if (ignoreScroll || !router.isScrollRestoring) {\n      return\n    }\n\n    let elementSelector = ''\n\n    if (event.target === document || event.target === window) {\n      elementSelector = 'window'\n    } else {\n      const attrId = (event.target as Element).getAttribute(\n        'data-scroll-restoration-id',\n      )\n\n      if (attrId) {\n        elementSelector = `[data-scroll-restoration-id=\"${attrId}\"]`\n      } else {\n        elementSelector = getCssSelector(event.target)\n      }\n    }\n\n    const restoreKey = getKey(router.state.location)\n\n    scrollRestorationCache.set((state) => {\n      const keyEntry = (state[restoreKey] =\n        state[restoreKey] || ({} as ScrollRestorationByElement))\n\n      const elementEntry = (keyEntry[elementSelector] =\n        keyEntry[elementSelector] || ({} as ScrollRestorationEntry))\n\n      if (elementSelector === 'window') {\n        elementEntry.scrollX = window.scrollX || 0\n        elementEntry.scrollY = window.scrollY || 0\n      } else if (elementSelector) {\n        const element = document.querySelector(elementSelector)\n        if (element) {\n          elementEntry.scrollX = element.scrollLeft || 0\n          elementEntry.scrollY = element.scrollTop || 0\n        }\n      }\n\n      return state\n    })\n  }\n\n  // Throttle the scroll event to avoid excessive updates\n  if (typeof document !== 'undefined') {\n    document.addEventListener('scroll', throttle(onScroll, 100), true)\n  }\n\n  router.subscribe('onRendered', (event) => {\n    // unobserveDom()\n\n    const cacheKey = getKey(event.toLocation)\n\n    // If the user doesn't want to restore the scroll position,\n    // we don't need to do anything.\n    if (!router.resetNextScroll) {\n      router.resetNextScroll = true\n      return\n    }\n\n    restoreScroll(\n      storageKey,\n      cacheKey,\n      router.options.scrollRestorationBehavior || undefined,\n      router.isScrollRestoring || undefined,\n      router.options.scrollToTopSelectors || undefined,\n    )\n\n    if (router.isScrollRestoring) {\n      // Mark the location as having been seen\n      scrollRestorationCache.set((state) => {\n        state[cacheKey] = state[cacheKey] || ({} as ScrollRestorationByElement)\n\n        return state\n      })\n    }\n  })\n}\n"],"names":["functionalUpdate","storageKey"],"mappings":";;;AAoBO,MAAM,aAAa;AAC1B,IAAI,kBAAkB;AACtB,IAAI;AACF,oBACE,OAAO,WAAW,eAAe,OAAO,OAAO,mBAAmB;AACtE,QAAQ;AAAC;AACT,MAAM,WAAW,CAAC,IAAmC,SAAiB;AAChE,MAAA;AACJ,SAAO,IAAI,SAAqB;AAC9B,QAAI,CAAC,SAAS;AACZ,gBAAU,WAAW,MAAM;AACzB,WAAG,GAAG,IAAI;AACA,kBAAA;AAAA,SACT,IAAI;AAAA,IAAA;AAAA,EAEX;AACF;AACa,MAAA,yBAAiD,mBACzD,MAAM;AACC,QAAA,QACJ,KAAK,MAAM,OAAO,eAAe,QAAQ,UAAU,KAAK,MAAM,KAAK,CAAC;AAE/D,SAAA;AAAA,IACL;AAAA;AAAA;AAAA;AAAA,IAIA,KAAK,CAAC,aACH,uBAAuB,QACtBA,MAAA,iBAAiB,SAAS,uBAAuB,KAAK,KACtD,uBAAuB,OACzB,OAAO,eAAe;AAAA,MACpB;AAAA,MACA,KAAK,UAAU,uBAAuB,KAAK;AAAA,IAC7C;AAAA,EAEJ;AACF,OACC;AAQQ,MAAA,iCAAiC,CAAC,aAA6B;AACnE,SAAA,SAAS,MAAM,OAAQ,SAAS;AACzC;AAEO,SAAS,eAAe,IAAiB;AAC9C,QAAM,OAAO,CAAC;AACV,MAAA;AACI,SAAA,SAAS,GAAG,YAAa;AAC1B,SAAA;AAAA,MACH,GAAG,GAAG,OAAO,cAAe,CAAA,EAAG,QAAgB,KAAK,OAAO,UAAU,EAAE,IAAI,CAAC;AAAA,IAC9E;AACK,SAAA;AAAA,EAAA;AAEP,SAAO,GAAG,KAAK,KAAK,KAAK,CAAC,GAAG,YAAY;AAC3C;AAEA,IAAI,eAAe;AAMZ,SAAS,cACdC,aACA,KACA,UACA,yBACA,sBACA;;AACI,MAAA;AAEA,MAAA;AACF,YAAQ,KAAK,MAAM,eAAe,QAAQA,WAAU,KAAK,IAAI;AAAA,WACtD,OAAY;AACnB,YAAQ,MAAM,KAAK;AACnB;AAAA,EAAA;AAGF,QAAM,cAAc,SAAO,YAAO,QAAQ,UAAf,mBAAsB;AAC3C,QAAA,iBAAiB,MAAM,WAAW;AAGzB,iBAAA;AAGd,GAAC,MAAM;AAGN,QAAI,2BAA2B,gBAAgB;AAC7C,iBAAW,mBAAmB,gBAAgB;AACtC,cAAA,QAAQ,eAAe,eAAe;AAC5C,YAAI,oBAAoB,UAAU;AAChC,iBAAO,SAAS;AAAA,YACd,KAAK,MAAM;AAAA,YACX,MAAM,MAAM;AAAA,YACZ;AAAA,UAAA,CACD;AAAA,mBACQ,iBAAiB;AACpB,gBAAA,UAAU,SAAS,cAAc,eAAe;AACtD,cAAI,SAAS;AACX,oBAAQ,aAAa,MAAM;AAC3B,oBAAQ,YAAY,MAAM;AAAA,UAAA;AAAA,QAC5B;AAAA,MACF;AAGF;AAAA,IAAA;AAOF,UAAM,OAAO,OAAO,SAAS,KAAK,MAAM,GAAG,EAAE,CAAC;AAE9C,QAAI,MAAM;AACR,YAAM,6BACH,OAAO,QAAQ,SAAS,CAAA,GAAI,+BAA+B;AAE9D,UAAI,2BAA2B;AACvB,cAAA,KAAK,SAAS,eAAe,IAAI;AACvC,YAAI,IAAI;AACN,aAAG,eAAe,yBAAyB;AAAA,QAAA;AAAA,MAC7C;AAGF;AAAA,IAAA;AAKD;AAAA,MACC;AAAA,MACA,IAAI,6DAAsB,OAAO,CAAC,MAAM,MAAM,cAAa,CAAA;AAAA,IAAC,EAC5D,QAAQ,CAAC,aAAa;AACtB,YAAM,UACJ,aAAa,WAAW,SAAS,SAAS,cAAc,QAAQ;AAClE,UAAI,SAAS;AACX,gBAAQ,SAAS;AAAA,UACf,KAAK;AAAA,UACL,MAAM;AAAA,UACN;AAAA,QAAA,CACD;AAAA,MAAA;AAAA,IACH,CACD;AAAA,EAAA,GACA;AAGY,iBAAA;AACjB;AAEgB,SAAA,uBAAuB,QAAmB,OAAiB;AACzE,QAAM,0BACJ,SAAS,OAAO,QAAQ,qBAAqB;AAE/C,MAAI,yBAAyB;AAC3B,WAAO,oBAAoB;AAAA,EAAA;AAG7B,MAAI,OAAO,aAAa,eAAe,OAAO,0BAA0B;AACtE;AAAA,EAAA;AAGF,SAAO,2BAA2B;AAGnB,iBAAA;AAET,QAAA,SACJ,OAAO,QAAQ,2BAA2B;AAE5C,SAAO,QAAQ,oBAAoB;AAuC7B,QAAA,WAAW,CAAC,UAAiB;AAG7B,QAAA,gBAAgB,CAAC,OAAO,mBAAmB;AAC7C;AAAA,IAAA;AAGF,QAAI,kBAAkB;AAEtB,QAAI,MAAM,WAAW,YAAY,MAAM,WAAW,QAAQ;AACtC,wBAAA;AAAA,IAAA,OACb;AACC,YAAA,SAAU,MAAM,OAAmB;AAAA,QACvC;AAAA,MACF;AAEA,UAAI,QAAQ;AACV,0BAAkB,gCAAgC,MAAM;AAAA,MAAA,OACnD;AACa,0BAAA,eAAe,MAAM,MAAM;AAAA,MAAA;AAAA,IAC/C;AAGF,UAAM,aAAa,OAAO,OAAO,MAAM,QAAQ;AAExB,2BAAA,IAAI,CAAC,UAAU;AACpC,YAAM,WAAY,MAAM,UAAU,IAChC,MAAM,UAAU,KAAM,CAAC;AAEzB,YAAM,eAAgB,SAAS,eAAe,IAC5C,SAAS,eAAe,KAAM,CAAC;AAEjC,UAAI,oBAAoB,UAAU;AACnB,qBAAA,UAAU,OAAO,WAAW;AAC5B,qBAAA,UAAU,OAAO,WAAW;AAAA,iBAChC,iBAAiB;AACpB,cAAA,UAAU,SAAS,cAAc,eAAe;AACtD,YAAI,SAAS;AACE,uBAAA,UAAU,QAAQ,cAAc;AAChC,uBAAA,UAAU,QAAQ,aAAa;AAAA,QAAA;AAAA,MAC9C;AAGK,aAAA;AAAA,IAAA,CACR;AAAA,EACH;AAGI,MAAA,OAAO,aAAa,aAAa;AACnC,aAAS,iBAAiB,UAAU,SAAS,UAAU,GAAG,GAAG,IAAI;AAAA,EAAA;AAG5D,SAAA,UAAU,cAAc,CAAC,UAAU;AAGlC,UAAA,WAAW,OAAO,MAAM,UAAU;AAIpC,QAAA,CAAC,OAAO,iBAAiB;AAC3B,aAAO,kBAAkB;AACzB;AAAA,IAAA;AAGF;AAAA,MACE;AAAA,MACA;AAAA,MACA,OAAO,QAAQ,6BAA6B;AAAA,MAC5C,OAAO,qBAAqB;AAAA,MAC5B,OAAO,QAAQ,wBAAwB;AAAA,IACzC;AAEA,QAAI,OAAO,mBAAmB;AAEL,6BAAA,IAAI,CAAC,UAAU;AACpC,cAAM,QAAQ,IAAI,MAAM,QAAQ,KAAM,CAAC;AAEhC,eAAA;AAAA,MAAA,CACR;AAAA,IAAA;AAAA,EACH,CACD;AACH;;;;;;;"}

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

@@ -0,0 +1,29 @@
+import { AnyRouter } from './router.cjs';
+import { ParsedLocation } from './location.cjs';
+import { NonNullableUpdater } from './utils.cjs';
+export type ScrollRestorationEntry = {
+    scrollX: number;
+    scrollY: number;
+};
+export type ScrollRestorationByElement = Record<string, ScrollRestorationEntry>;
+export type ScrollRestorationByKey = Record<string, ScrollRestorationByElement>;
+export type ScrollRestorationCache = {
+    state: ScrollRestorationByKey;
+    set: (updater: NonNullableUpdater<ScrollRestorationByKey>) => void;
+};
+export type ScrollRestorationOptions = {
+    getKey?: (location: ParsedLocation) => string;
+    scrollBehavior?: ScrollToOptions['behavior'];
+};
+export declare const storageKey = "tsr-scroll-restoration-v1_3";
+export declare const scrollRestorationCache: ScrollRestorationCache;
+/**
+ * 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.
+ */
+export declare const defaultGetScrollRestorationKey: (location: ParsedLocation) => string;
+export declare function getCssSelector(el: any): string;
+export declare function restoreScroll(storageKey: string, key: string | undefined, behavior: ScrollToOptions['behavior'] | undefined, shouldScrollRestoration: boolean | undefined, scrollToTopSelectors: Array<string> | undefined): void;
+export declare function setupScrollRestoration(router: AnyRouter, force?: boolean): void;

package/dist/cjs/typePrimitives.d.cts

@@ -0,0 +1,65 @@
+import { FromPathOption, NavigateOptions, PathParamOptions, SearchParamOptions, ToPathOption } from './link.cjs';
+import { Redirect } from './redirect.cjs';
+import { RouteIds } from './routeInfo.cjs';
+import { AnyRouter, RegisteredRouter } from './router.cjs';
+import { UseParamsResult } from './useParams.cjs';
+import { UseSearchResult } from './useSearch.cjs';
+import { Constrain, ConstrainLiteral } from './utils.cjs';
+export type ValidateFromPath<TRouter extends AnyRouter = RegisteredRouter, TFrom = string> = FromPathOption<TRouter, TFrom>;
+export type ValidateToPath<TRouter extends AnyRouter = RegisteredRouter, TTo extends string | undefined = undefined, TFrom extends string = string> = ToPathOption<TRouter, TFrom, TTo>;
+export type ValidateSearch<TRouter extends AnyRouter = RegisteredRouter, TTo extends string | undefined = undefined, TFrom extends string = string> = SearchParamOptions<TRouter, TFrom, TTo>;
+export type ValidateParams<TRouter extends AnyRouter = RegisteredRouter, TTo extends string | undefined = undefined, TFrom extends string = string> = PathParamOptions<TRouter, TFrom, TTo>;
+/**
+ * @internal
+ */
+export type InferFrom<TOptions, TDefaultFrom extends string = string> = TOptions extends {
+    from: infer TFrom extends string;
+} ? TFrom : TDefaultFrom;
+/**
+ * @internal
+ */
+export type InferTo<TOptions> = TOptions extends {
+    to: infer TTo extends string;
+} ? TTo : undefined;
+/**
+ * @internal
+ */
+export type InferMaskTo<TOptions> = TOptions extends {
+    mask: {
+        to: infer TTo extends string;
+    };
+} ? TTo : '';
+export type InferMaskFrom<TOptions> = TOptions extends {
+    mask: {
+        from: infer TFrom extends string;
+    };
+} ? TFrom : string;
+export type ValidateNavigateOptions<TRouter extends AnyRouter = RegisteredRouter, TOptions = unknown, TDefaultFrom extends string = string> = Constrain<TOptions, NavigateOptions<TRouter, InferFrom<TOptions, TDefaultFrom>, InferTo<TOptions>, InferMaskFrom<TOptions>, InferMaskTo<TOptions>>>;
+export type ValidateNavigateOptionsArray<TRouter extends AnyRouter = RegisteredRouter, TOptions extends ReadonlyArray<any> = ReadonlyArray<unknown>, TDefaultFrom extends string = string> = {
+    [K in keyof TOptions]: ValidateNavigateOptions<TRouter, TOptions[K], TDefaultFrom>;
+};
+export type ValidateRedirectOptions<TRouter extends AnyRouter = RegisteredRouter, TOptions = unknown, TDefaultFrom extends string = string> = Constrain<TOptions, Redirect<TRouter, InferFrom<TOptions, TDefaultFrom>, InferTo<TOptions>, InferMaskFrom<TOptions>, InferMaskTo<TOptions>>>;
+export type ValidateRedirectOptionsArray<TRouter extends AnyRouter = RegisteredRouter, TOptions extends ReadonlyArray<any> = ReadonlyArray<unknown>, TDefaultFrom extends string = string> = {
+    [K in keyof TOptions]: ValidateRedirectOptions<TRouter, TOptions[K], TDefaultFrom>;
+};
+export type ValidateId<TRouter extends AnyRouter = RegisteredRouter, TId extends string = string> = ConstrainLiteral<TId, RouteIds<TRouter['routeTree']>>;
+/**
+ * @internal
+ */
+export type InferStrict<TOptions> = TOptions extends {
+    strict: infer TStrict extends boolean;
+} ? TStrict : true;
+/**
+ * @internal
+ */
+export type InferShouldThrow<TOptions> = TOptions extends {
+    shouldThrow: infer TShouldThrow extends boolean;
+} ? TShouldThrow : true;
+/**
+ * @internal
+ */
+export type InferSelected<TOptions> = TOptions extends {
+    select: (...args: Array<any>) => infer TSelected;
+} ? TSelected : unknown;
+export type ValidateUseSearchResult<TOptions, TRouter extends AnyRouter = RegisteredRouter> = UseSearchResult<TRouter, InferFrom<TOptions>, InferStrict<TOptions>, InferSelected<TOptions>>;
+export type ValidateUseParamsResult<TOptions, TRouter extends AnyRouter = RegisteredRouter> = Constrain<TOptions, UseParamsResult<TRouter, InferFrom<TOptions>, InferStrict<TOptions>, InferSelected<TOptions>>>;

package/dist/esm/index.d.ts

@@ -35,3 +35,6 @@ export type { Redirect, ResolvedRedirect, AnyRedirect } from './redirect.js';
 export { redirect, isRedirect, isResolvedRedirect } from './redirect.js';
 export type { NotFoundError } from './not-found.js';
 export { isNotFound, notFound } from './not-found.js';
+export { defaultGetScrollRestorationKey, restoreScroll, storageKey, getCssSelector, scrollRestorationCache, setupScrollRestoration, } from './scroll-restoration.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';

package/dist/esm/index.js

@@ -10,12 +10,14 @@ import { defaultParseSearch, defaultStringifySearch, parseSearchWith, stringifyS
 import { createControlledPromise, deepEqual, escapeJSON, functionalUpdate, isPlainArray, isPlainObject, last, pick, replaceEqualDeep, shallow } from "./utils.js";
 import { isRedirect, isResolvedRedirect, redirect } from "./redirect.js";
 import { isNotFound, notFound } from "./not-found.js";
+import { defaultGetScrollRestorationKey, getCssSelector, restoreScroll, scrollRestorationCache, setupScrollRestoration, storageKey } from "./scroll-restoration.js";
 export {
   TSR_DEFERRED_PROMISE,
   cleanPath,
   createControlledPromise,
   decode,
   deepEqual,
+  defaultGetScrollRestorationKey,
   defaultParseSearch,
   defaultSerializeError,
   defaultStringifySearch,
@@ -24,6 +26,7 @@ export {
   escapeJSON,
   exactPathTest,
   functionalUpdate,
+  getCssSelector,
   getLocationChangeInfo,
   interpolatePath,
   isMatch,
@@ -46,9 +49,13 @@ export {
   removeTrailingSlash,
   replaceEqualDeep,
   resolvePath,
+  restoreScroll,
   retainSearchParams,
   rootRouteId,
+  scrollRestorationCache,
+  setupScrollRestoration,
   shallow,
+  storageKey,
   stringifySearchWith,
   stripSearchParams,
   trimPath,

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;"}

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

@@ -0,0 +1,29 @@
+import { AnyRouter } from './router.js';
+import { ParsedLocation } from './location.js';
+import { NonNullableUpdater } from './utils.js';
+export type ScrollRestorationEntry = {
+    scrollX: number;
+    scrollY: number;
+};
+export type ScrollRestorationByElement = Record<string, ScrollRestorationEntry>;
+export type ScrollRestorationByKey = Record<string, ScrollRestorationByElement>;
+export type ScrollRestorationCache = {
+    state: ScrollRestorationByKey;
+    set: (updater: NonNullableUpdater<ScrollRestorationByKey>) => void;
+};
+export type ScrollRestorationOptions = {
+    getKey?: (location: ParsedLocation) => string;
+    scrollBehavior?: ScrollToOptions['behavior'];
+};
+export declare const storageKey = "tsr-scroll-restoration-v1_3";
+export declare const scrollRestorationCache: ScrollRestorationCache;
+/**
+ * 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.
+ */
+export declare const defaultGetScrollRestorationKey: (location: ParsedLocation) => string;
+export declare function getCssSelector(el: any): string;
+export declare function restoreScroll(storageKey: string, key: string | undefined, behavior: ScrollToOptions['behavior'] | undefined, shouldScrollRestoration: boolean | undefined, scrollToTopSelectors: Array<string> | undefined): void;
+export declare function setupScrollRestoration(router: AnyRouter, force?: boolean): void;

package/dist/esm/scroll-restoration.js

@@ -0,0 +1,184 @@
+import { functionalUpdate } from "./utils.js";
+const storageKey = "tsr-scroll-restoration-v1_3";
+let sessionsStorage = false;
+try {
+  sessionsStorage = typeof window !== "undefined" && typeof window.sessionStorage === "object";
+} catch {
+}
+const throttle = (fn, wait) => {
+  let timeout;
+  return (...args) => {
+    if (!timeout) {
+      timeout = setTimeout(() => {
+        fn(...args);
+        timeout = null;
+      }, wait);
+    }
+  };
+};
+const scrollRestorationCache = sessionsStorage ? (() => {
+  const state = JSON.parse(window.sessionStorage.getItem(storageKey) || "null") || {};
+  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) => (scrollRestorationCache.state = functionalUpdate(updater, scrollRestorationCache.state) || scrollRestorationCache.state, window.sessionStorage.setItem(
+      storageKey,
+      JSON.stringify(scrollRestorationCache.state)
+    ))
+  };
+})() : void 0;
+const defaultGetScrollRestorationKey = (location) => {
+  return location.state.key || location.href;
+};
+function getCssSelector(el) {
+  const path = [];
+  let parent;
+  while (parent = el.parentNode) {
+    path.unshift(
+      `${el.tagName}:nth-child(${[].indexOf.call(parent.children, el) + 1})`
+    );
+    el = parent;
+  }
+  return `${path.join(" > ")}`.toLowerCase();
+}
+let ignoreScroll = false;
+function restoreScroll(storageKey2, key, behavior, shouldScrollRestoration, scrollToTopSelectors) {
+  var _a;
+  let byKey;
+  try {
+    byKey = JSON.parse(sessionStorage.getItem(storageKey2) || "{}");
+  } catch (error) {
+    console.error(error);
+    return;
+  }
+  const resolvedKey = key || ((_a = window.history.state) == null ? void 0 : _a.key);
+  const elementEntries = byKey[resolvedKey];
+  ignoreScroll = true;
+  (() => {
+    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;
+          }
+        }
+      }
+      return;
+    }
+    const hash = window.location.hash.split("#")[1];
+    if (hash) {
+      const hashScrollIntoViewOptions = (window.history.state || {}).__hashScrollIntoViewOptions ?? true;
+      if (hashScrollIntoViewOptions) {
+        const el = document.getElementById(hash);
+        if (el) {
+          el.scrollIntoView(hashScrollIntoViewOptions);
+        }
+      }
+      return;
+    }
+    [
+      "window",
+      ...(scrollToTopSelectors == null ? void 0 : scrollToTopSelectors.filter((d) => d !== "window")) ?? []
+    ].forEach((selector) => {
+      const element = selector === "window" ? window : document.querySelector(selector);
+      if (element) {
+        element.scrollTo({
+          top: 0,
+          left: 0,
+          behavior
+        });
+      }
+    });
+  })();
+  ignoreScroll = false;
+}
+function setupScrollRestoration(router, force) {
+  const shouldScrollRestoration = force ?? router.options.scrollRestoration ?? false;
+  if (shouldScrollRestoration) {
+    router.isScrollRestoring = true;
+  }
+  if (typeof document === "undefined" || router.isScrollRestorationSetup) {
+    return;
+  }
+  router.isScrollRestorationSetup = true;
+  ignoreScroll = false;
+  const getKey = router.options.getScrollRestorationKey || defaultGetScrollRestorationKey;
+  window.history.scrollRestoration = "manual";
+  const onScroll = (event) => {
+    if (ignoreScroll || !router.isScrollRestoring) {
+      return;
+    }
+    let elementSelector = "";
+    if (event.target === document || event.target === window) {
+      elementSelector = "window";
+    } else {
+      const attrId = event.target.getAttribute(
+        "data-scroll-restoration-id"
+      );
+      if (attrId) {
+        elementSelector = `[data-scroll-restoration-id="${attrId}"]`;
+      } else {
+        elementSelector = getCssSelector(event.target);
+      }
+    }
+    const restoreKey = getKey(router.state.location);
+    scrollRestorationCache.set((state) => {
+      const keyEntry = state[restoreKey] = state[restoreKey] || {};
+      const elementEntry = keyEntry[elementSelector] = 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;
+        }
+      }
+      return state;
+    });
+  };
+  if (typeof document !== "undefined") {
+    document.addEventListener("scroll", throttle(onScroll, 100), true);
+  }
+  router.subscribe("onRendered", (event) => {
+    const cacheKey = getKey(event.toLocation);
+    if (!router.resetNextScroll) {
+      router.resetNextScroll = true;
+      return;
+    }
+    restoreScroll(
+      storageKey,
+      cacheKey,
+      router.options.scrollRestorationBehavior || void 0,
+      router.isScrollRestoring || void 0,
+      router.options.scrollToTopSelectors || void 0
+    );
+    if (router.isScrollRestoring) {
+      scrollRestorationCache.set((state) => {
+        state[cacheKey] = state[cacheKey] || {};
+        return state;
+      });
+    }
+  });
+}
+export {
+  defaultGetScrollRestorationKey,
+  getCssSelector,
+  restoreScroll,
+  scrollRestorationCache,
+  setupScrollRestoration,
+  storageKey
+};
+//# sourceMappingURL=scroll-restoration.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-restoration.js","sources":["../../src/scroll-restoration.ts"],"sourcesContent":["import { functionalUpdate } from './utils'\nimport type { AnyRouter } from './router'\nimport type { ParsedLocation } from './location'\nimport type { NonNullableUpdater } from './utils'\n\nexport type ScrollRestorationEntry = { scrollX: number; scrollY: number }\n\nexport type ScrollRestorationByElement = Record<string, ScrollRestorationEntry>\n\nexport type ScrollRestorationByKey = Record<string, ScrollRestorationByElement>\n\nexport type ScrollRestorationCache = {\n  state: ScrollRestorationByKey\n  set: (updater: NonNullableUpdater<ScrollRestorationByKey>) => void\n}\nexport type ScrollRestorationOptions = {\n  getKey?: (location: ParsedLocation) => string\n  scrollBehavior?: ScrollToOptions['behavior']\n}\n\nexport const storageKey = 'tsr-scroll-restoration-v1_3'\nlet sessionsStorage = false\ntry {\n  sessionsStorage =\n    typeof window !== 'undefined' && typeof window.sessionStorage === 'object'\n} catch {}\nconst throttle = (fn: (...args: Array<any>) => void, wait: number) => {\n  let timeout: any\n  return (...args: Array<any>) => {\n    if (!timeout) {\n      timeout = setTimeout(() => {\n        fn(...args)\n        timeout = null\n      }, wait)\n    }\n  }\n}\nexport const scrollRestorationCache: ScrollRestorationCache = sessionsStorage\n  ? (() => {\n      const state: ScrollRestorationByKey =\n        JSON.parse(window.sessionStorage.getItem(storageKey) || 'null') || {}\n\n      return {\n        state,\n        // This setter is simply to make sure that we set the sessionStorage right\n        // after the state is updated. It doesn't necessarily need to be a functional\n        // update.\n        set: (updater) => (\n          (scrollRestorationCache.state =\n            functionalUpdate(updater, scrollRestorationCache.state) ||\n            scrollRestorationCache.state),\n          window.sessionStorage.setItem(\n            storageKey,\n            JSON.stringify(scrollRestorationCache.state),\n          )\n        ),\n      }\n    })()\n  : (undefined as any)\n/**\n * The default `getKey` function for `useScrollRestoration`.\n * It returns the `key` from the location state or the `href` of the location.\n *\n * The `location.href` is used as a fallback to support the use case where the location state is not available like the initial render.\n */\n\nexport const defaultGetScrollRestorationKey = (location: ParsedLocation) => {\n  return location.state.key! || location.href\n}\n\nexport function getCssSelector(el: any): string {\n  const path = []\n  let parent\n  while ((parent = el.parentNode)) {\n    path.unshift(\n      `${el.tagName}:nth-child(${([].indexOf as any).call(parent.children, el) + 1})`,\n    )\n    el = parent\n  }\n  return `${path.join(' > ')}`.toLowerCase()\n}\n\nlet ignoreScroll = false\n\n// NOTE: This function must remain pure and not use any outside variables\n// unless they are passed in as arguments. Why? Because we need to be able to\n// toString() it into a script tag to execute as early as possible in the browser\n// during SSR. Additionally, we also call it from within the router lifecycle\nexport function restoreScroll(\n  storageKey: string,\n  key: string | undefined,\n  behavior: ScrollToOptions['behavior'] | undefined,\n  shouldScrollRestoration: boolean | undefined,\n  scrollToTopSelectors: Array<string> | undefined,\n) {\n  let byKey: ScrollRestorationByKey\n\n  try {\n    byKey = JSON.parse(sessionStorage.getItem(storageKey) || '{}')\n  } catch (error: any) {\n    console.error(error)\n    return\n  }\n\n  const resolvedKey = key || window.history.state?.key\n  const elementEntries = byKey[resolvedKey]\n\n  //\n  ignoreScroll = true\n\n  //\n  ;(() => {\n    // If we have a cached entry for this location state,\n    // we always need to prefer that over the hash scroll.\n    if (shouldScrollRestoration && elementEntries) {\n      for (const elementSelector in elementEntries) {\n        const entry = elementEntries[elementSelector]!\n        if (elementSelector === 'window') {\n          window.scrollTo({\n            top: entry.scrollY,\n            left: entry.scrollX,\n            behavior,\n          })\n        } else if (elementSelector) {\n          const element = document.querySelector(elementSelector)\n          if (element) {\n            element.scrollLeft = entry.scrollX\n            element.scrollTop = entry.scrollY\n          }\n        }\n      }\n\n      return\n    }\n\n    // If we don't have a cached entry for the hash,\n    // Which means we've never seen this location before,\n    // we need to check if there is a hash in the URL.\n    // If there is, we need to scroll it's ID into view.\n    const hash = window.location.hash.split('#')[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    // If there is no cached entry for the hash and there is no hash in the URL,\n    // we need to scroll to the top of the page for every scrollToTop element\n    ;[\n      'window',\n      ...(scrollToTopSelectors?.filter((d) => d !== 'window') ?? []),\n    ].forEach((selector) => {\n      const element =\n        selector === 'window' ? window : document.querySelector(selector)\n      if (element) {\n        element.scrollTo({\n          top: 0,\n          left: 0,\n          behavior,\n        })\n      }\n    })\n  })()\n\n  //\n  ignoreScroll = false\n}\n\nexport function setupScrollRestoration(router: AnyRouter, force?: boolean) {\n  const shouldScrollRestoration =\n    force ?? router.options.scrollRestoration ?? false\n\n  if (shouldScrollRestoration) {\n    router.isScrollRestoring = true\n  }\n\n  if (typeof document === 'undefined' || router.isScrollRestorationSetup) {\n    return\n  }\n\n  router.isScrollRestorationSetup = true\n\n  //\n  ignoreScroll = false\n\n  const getKey =\n    router.options.getScrollRestorationKey || defaultGetScrollRestorationKey\n\n  window.history.scrollRestoration = 'manual'\n\n  // // Create a MutationObserver to monitor DOM changes\n  // const mutationObserver = new MutationObserver(() => {\n  //   ;ignoreScroll = true\n  //   requestAnimationFrame(() => {\n  //     ;ignoreScroll = false\n\n  //     // Attempt to restore scroll position on each dom\n  //     // mutation until the user scrolls. We do this\n  //     // because dynamic content may come in at different\n  //     // ticks after the initial render and we want to\n  //     // keep up with that content as much as possible.\n  //     // As soon as the user scrolls, we no longer need\n  //     // to attempt router.\n  //     // console.log('mutation observer restoreScroll')\n  //     restoreScroll(\n  //       storageKey,\n  //       getKey(router.state.location),\n  //       router.options.scrollRestorationBehavior,\n  //     )\n  //   })\n  // })\n\n  // const observeDom = () => {\n  //   // Observe changes to the entire document\n  //   mutationObserver.observe(document, {\n  //     childList: true, // Detect added or removed child nodes\n  //     subtree: true, // Monitor all descendants\n  //     characterData: true, // Detect text content changes\n  //   })\n  // }\n\n  // const unobserveDom = () => {\n  //   mutationObserver.disconnect()\n  // }\n\n  // observeDom()\n\n  const onScroll = (event: Event) => {\n    // unobserveDom()\n\n    if (ignoreScroll || !router.isScrollRestoring) {\n      return\n    }\n\n    let elementSelector = ''\n\n    if (event.target === document || event.target === window) {\n      elementSelector = 'window'\n    } else {\n      const attrId = (event.target as Element).getAttribute(\n        'data-scroll-restoration-id',\n      )\n\n      if (attrId) {\n        elementSelector = `[data-scroll-restoration-id=\"${attrId}\"]`\n      } else {\n        elementSelector = getCssSelector(event.target)\n      }\n    }\n\n    const restoreKey = getKey(router.state.location)\n\n    scrollRestorationCache.set((state) => {\n      const keyEntry = (state[restoreKey] =\n        state[restoreKey] || ({} as ScrollRestorationByElement))\n\n      const elementEntry = (keyEntry[elementSelector] =\n        keyEntry[elementSelector] || ({} as ScrollRestorationEntry))\n\n      if (elementSelector === 'window') {\n        elementEntry.scrollX = window.scrollX || 0\n        elementEntry.scrollY = window.scrollY || 0\n      } else if (elementSelector) {\n        const element = document.querySelector(elementSelector)\n        if (element) {\n          elementEntry.scrollX = element.scrollLeft || 0\n          elementEntry.scrollY = element.scrollTop || 0\n        }\n      }\n\n      return state\n    })\n  }\n\n  // Throttle the scroll event to avoid excessive updates\n  if (typeof document !== 'undefined') {\n    document.addEventListener('scroll', throttle(onScroll, 100), true)\n  }\n\n  router.subscribe('onRendered', (event) => {\n    // unobserveDom()\n\n    const cacheKey = getKey(event.toLocation)\n\n    // If the user doesn't want to restore the scroll position,\n    // we don't need to do anything.\n    if (!router.resetNextScroll) {\n      router.resetNextScroll = true\n      return\n    }\n\n    restoreScroll(\n      storageKey,\n      cacheKey,\n      router.options.scrollRestorationBehavior || undefined,\n      router.isScrollRestoring || undefined,\n      router.options.scrollToTopSelectors || undefined,\n    )\n\n    if (router.isScrollRestoring) {\n      // Mark the location as having been seen\n      scrollRestorationCache.set((state) => {\n        state[cacheKey] = state[cacheKey] || ({} as ScrollRestorationByElement)\n\n        return state\n      })\n    }\n  })\n}\n"],"names":["storageKey"],"mappings":"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"}

package/dist/esm/typePrimitives.d.ts

@@ -0,0 +1,65 @@
+import { FromPathOption, NavigateOptions, PathParamOptions, SearchParamOptions, ToPathOption } from './link.js';
+import { Redirect } from './redirect.js';
+import { RouteIds } from './routeInfo.js';
+import { AnyRouter, RegisteredRouter } from './router.js';
+import { UseParamsResult } from './useParams.js';
+import { UseSearchResult } from './useSearch.js';
+import { Constrain, ConstrainLiteral } from './utils.js';
+export type ValidateFromPath<TRouter extends AnyRouter = RegisteredRouter, TFrom = string> = FromPathOption<TRouter, TFrom>;
+export type ValidateToPath<TRouter extends AnyRouter = RegisteredRouter, TTo extends string | undefined = undefined, TFrom extends string = string> = ToPathOption<TRouter, TFrom, TTo>;
+export type ValidateSearch<TRouter extends AnyRouter = RegisteredRouter, TTo extends string | undefined = undefined, TFrom extends string = string> = SearchParamOptions<TRouter, TFrom, TTo>;
+export type ValidateParams<TRouter extends AnyRouter = RegisteredRouter, TTo extends string | undefined = undefined, TFrom extends string = string> = PathParamOptions<TRouter, TFrom, TTo>;
+/**
+ * @internal
+ */
+export type InferFrom<TOptions, TDefaultFrom extends string = string> = TOptions extends {
+    from: infer TFrom extends string;
+} ? TFrom : TDefaultFrom;
+/**
+ * @internal
+ */
+export type InferTo<TOptions> = TOptions extends {
+    to: infer TTo extends string;
+} ? TTo : undefined;
+/**
+ * @internal
+ */
+export type InferMaskTo<TOptions> = TOptions extends {
+    mask: {
+        to: infer TTo extends string;
+    };
+} ? TTo : '';
+export type InferMaskFrom<TOptions> = TOptions extends {
+    mask: {
+        from: infer TFrom extends string;
+    };
+} ? TFrom : string;
+export type ValidateNavigateOptions<TRouter extends AnyRouter = RegisteredRouter, TOptions = unknown, TDefaultFrom extends string = string> = Constrain<TOptions, NavigateOptions<TRouter, InferFrom<TOptions, TDefaultFrom>, InferTo<TOptions>, InferMaskFrom<TOptions>, InferMaskTo<TOptions>>>;
+export type ValidateNavigateOptionsArray<TRouter extends AnyRouter = RegisteredRouter, TOptions extends ReadonlyArray<any> = ReadonlyArray<unknown>, TDefaultFrom extends string = string> = {
+    [K in keyof TOptions]: ValidateNavigateOptions<TRouter, TOptions[K], TDefaultFrom>;
+};
+export type ValidateRedirectOptions<TRouter extends AnyRouter = RegisteredRouter, TOptions = unknown, TDefaultFrom extends string = string> = Constrain<TOptions, Redirect<TRouter, InferFrom<TOptions, TDefaultFrom>, InferTo<TOptions>, InferMaskFrom<TOptions>, InferMaskTo<TOptions>>>;
+export type ValidateRedirectOptionsArray<TRouter extends AnyRouter = RegisteredRouter, TOptions extends ReadonlyArray<any> = ReadonlyArray<unknown>, TDefaultFrom extends string = string> = {
+    [K in keyof TOptions]: ValidateRedirectOptions<TRouter, TOptions[K], TDefaultFrom>;
+};
+export type ValidateId<TRouter extends AnyRouter = RegisteredRouter, TId extends string = string> = ConstrainLiteral<TId, RouteIds<TRouter['routeTree']>>;
+/**
+ * @internal
+ */
+export type InferStrict<TOptions> = TOptions extends {
+    strict: infer TStrict extends boolean;
+} ? TStrict : true;
+/**
+ * @internal
+ */
+export type InferShouldThrow<TOptions> = TOptions extends {
+    shouldThrow: infer TShouldThrow extends boolean;
+} ? TShouldThrow : true;
+/**
+ * @internal
+ */
+export type InferSelected<TOptions> = TOptions extends {
+    select: (...args: Array<any>) => infer TSelected;
+} ? TSelected : unknown;
+export type ValidateUseSearchResult<TOptions, TRouter extends AnyRouter = RegisteredRouter> = UseSearchResult<TRouter, InferFrom<TOptions>, InferStrict<TOptions>, InferSelected<TOptions>>;
+export type ValidateUseParamsResult<TOptions, TRouter extends AnyRouter = RegisteredRouter> = Constrain<TOptions, UseParamsResult<TRouter, InferFrom<TOptions>, InferStrict<TOptions>, InferSelected<TOptions>>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/router-core",
-  "version": "1.114.12",
+  "version": "1.114.16",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",

package/src/index.ts

@@ -362,3 +362,38 @@ export { redirect, isRedirect, isResolvedRedirect } from './redirect'
 
 export type { NotFoundError } from './not-found'
 export { isNotFound, notFound } from './not-found'
+
+export {
+  defaultGetScrollRestorationKey,
+  restoreScroll,
+  storageKey,
+  getCssSelector,
+  scrollRestorationCache,
+  setupScrollRestoration,
+} from './scroll-restoration'
+
+export type {
+  ScrollRestorationOptions,
+  ScrollRestorationEntry,
+} from './scroll-restoration'
+
+export type {
+  ValidateFromPath,
+  ValidateToPath,
+  ValidateSearch,
+  ValidateParams,
+  InferFrom,
+  InferTo,
+  InferMaskTo,
+  InferMaskFrom,
+  ValidateNavigateOptions,
+  ValidateNavigateOptionsArray,
+  ValidateRedirectOptions,
+  ValidateRedirectOptionsArray,
+  ValidateId,
+  InferStrict,
+  InferShouldThrow,
+  InferSelected,
+  ValidateUseSearchResult,
+  ValidateUseParamsResult,
+} from './typePrimitives'

package/src/scroll-restoration.ts

@@ -0,0 +1,318 @@
+import { functionalUpdate } from './utils'
+import type { AnyRouter } from './router'
+import type { ParsedLocation } from './location'
+import type { NonNullableUpdater } from './utils'
+
+export type ScrollRestorationEntry = { scrollX: number; scrollY: number }
+
+export type ScrollRestorationByElement = Record<string, ScrollRestorationEntry>
+
+export type ScrollRestorationByKey = Record<string, ScrollRestorationByElement>
+
+export type ScrollRestorationCache = {
+  state: ScrollRestorationByKey
+  set: (updater: NonNullableUpdater<ScrollRestorationByKey>) => void
+}
+export type ScrollRestorationOptions = {
+  getKey?: (location: ParsedLocation) => string
+  scrollBehavior?: ScrollToOptions['behavior']
+}
+
+export const storageKey = 'tsr-scroll-restoration-v1_3'
+let sessionsStorage = false
+try {
+  sessionsStorage =
+    typeof window !== 'undefined' && typeof window.sessionStorage === 'object'
+} catch {}
+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 state: ScrollRestorationByKey =
+        JSON.parse(window.sessionStorage.getItem(storageKey) || 'null') || {}
+
+      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) => (
+          (scrollRestorationCache.state =
+            functionalUpdate(updater, scrollRestorationCache.state) ||
+            scrollRestorationCache.state),
+          window.sessionStorage.setItem(
+            storageKey,
+            JSON.stringify(scrollRestorationCache.state),
+          )
+        ),
+      }
+    })()
+  : (undefined as any)
+/**
+ * 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.
+ */
+
+export const defaultGetScrollRestorationKey = (location: ParsedLocation) => {
+  return location.state.key! || location.href
+}
+
+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()
+}
+
+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 | undefined,
+  behavior: ScrollToOptions['behavior'] | undefined,
+  shouldScrollRestoration: boolean | undefined,
+  scrollToTopSelectors: Array<string> | undefined,
+) {
+  let byKey: ScrollRestorationByKey
+
+  try {
+    byKey = JSON.parse(sessionStorage.getItem(storageKey) || '{}')
+  } catch (error: any) {
+    console.error(error)
+    return
+  }
+
+  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
+          }
+        }
+      }
+
+      return
+    }
+
+    // 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]
+
+    if (hash) {
+      const hashScrollIntoViewOptions =
+        (window.history.state || {}).__hashScrollIntoViewOptions ?? true
+
+      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 for every scrollToTop element
+    ;[
+      'window',
+      ...(scrollToTopSelectors?.filter((d) => d !== 'window') ?? []),
+    ].forEach((selector) => {
+      const element =
+        selector === 'window' ? window : document.querySelector(selector)
+      if (element) {
+        element.scrollTo({
+          top: 0,
+          left: 0,
+          behavior,
+        })
+      }
+    })
+  })()
+
+  //
+  ignoreScroll = false
+}
+
+export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
+  const shouldScrollRestoration =
+    force ?? router.options.scrollRestoration ?? false
+
+  if (shouldScrollRestoration) {
+    router.isScrollRestoring = true
+  }
+
+  if (typeof document === 'undefined' || router.isScrollRestorationSetup) {
+    return
+  }
+
+  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
+    }
+
+    let elementSelector = ''
+
+    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)
+      }
+    }
+
+    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
+        }
+      }
+
+      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()
+
+    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
+    }
+
+    restoreScroll(
+      storageKey,
+      cacheKey,
+      router.options.scrollRestorationBehavior || undefined,
+      router.isScrollRestoring || undefined,
+      router.options.scrollToTopSelectors || undefined,
+    )
+
+    if (router.isScrollRestoring) {
+      // Mark the location as having been seen
+      scrollRestorationCache.set((state) => {
+        state[cacheKey] = state[cacheKey] || ({} as ScrollRestorationByElement)
+
+        return state
+      })
+    }
+  })
+}

package/src/typePrimitives.ts

@@ -0,0 +1,181 @@
+import type {
+  FromPathOption,
+  NavigateOptions,
+  PathParamOptions,
+  SearchParamOptions,
+  ToPathOption,
+} from './link'
+import type { Redirect } from './redirect'
+import type { RouteIds } from './routeInfo'
+import type { AnyRouter, RegisteredRouter } from './router'
+import type { UseParamsResult } from './useParams'
+import type { UseSearchResult } from './useSearch'
+import type { Constrain, ConstrainLiteral } from './utils'
+
+export type ValidateFromPath<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TFrom = string,
+> = FromPathOption<TRouter, TFrom>
+
+export type ValidateToPath<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TTo extends string | undefined = undefined,
+  TFrom extends string = string,
+> = ToPathOption<TRouter, TFrom, TTo>
+
+export type ValidateSearch<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TTo extends string | undefined = undefined,
+  TFrom extends string = string,
+> = SearchParamOptions<TRouter, TFrom, TTo>
+
+export type ValidateParams<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TTo extends string | undefined = undefined,
+  TFrom extends string = string,
+> = PathParamOptions<TRouter, TFrom, TTo>
+
+/**
+ * @internal
+ */
+export type InferFrom<
+  TOptions,
+  TDefaultFrom extends string = string,
+> = TOptions extends {
+  from: infer TFrom extends string
+}
+  ? TFrom
+  : TDefaultFrom
+
+/**
+ * @internal
+ */
+export type InferTo<TOptions> = TOptions extends {
+  to: infer TTo extends string
+}
+  ? TTo
+  : undefined
+
+/**
+ * @internal
+ */
+export type InferMaskTo<TOptions> = TOptions extends {
+  mask: { to: infer TTo extends string }
+}
+  ? TTo
+  : ''
+
+export type InferMaskFrom<TOptions> = TOptions extends {
+  mask: { from: infer TFrom extends string }
+}
+  ? TFrom
+  : string
+
+export type ValidateNavigateOptions<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TOptions = unknown,
+  TDefaultFrom extends string = string,
+> = Constrain<
+  TOptions,
+  NavigateOptions<
+    TRouter,
+    InferFrom<TOptions, TDefaultFrom>,
+    InferTo<TOptions>,
+    InferMaskFrom<TOptions>,
+    InferMaskTo<TOptions>
+  >
+>
+
+export type ValidateNavigateOptionsArray<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TOptions extends ReadonlyArray<any> = ReadonlyArray<unknown>,
+  TDefaultFrom extends string = string,
+> = {
+  [K in keyof TOptions]: ValidateNavigateOptions<
+    TRouter,
+    TOptions[K],
+    TDefaultFrom
+  >
+}
+
+export type ValidateRedirectOptions<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TOptions = unknown,
+  TDefaultFrom extends string = string,
+> = Constrain<
+  TOptions,
+  Redirect<
+    TRouter,
+    InferFrom<TOptions, TDefaultFrom>,
+    InferTo<TOptions>,
+    InferMaskFrom<TOptions>,
+    InferMaskTo<TOptions>
+  >
+>
+
+export type ValidateRedirectOptionsArray<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TOptions extends ReadonlyArray<any> = ReadonlyArray<unknown>,
+  TDefaultFrom extends string = string,
+> = {
+  [K in keyof TOptions]: ValidateRedirectOptions<
+    TRouter,
+    TOptions[K],
+    TDefaultFrom
+  >
+}
+
+export type ValidateId<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TId extends string = string,
+> = ConstrainLiteral<TId, RouteIds<TRouter['routeTree']>>
+
+/**
+ * @internal
+ */
+export type InferStrict<TOptions> = TOptions extends {
+  strict: infer TStrict extends boolean
+}
+  ? TStrict
+  : true
+
+/**
+ * @internal
+ */
+export type InferShouldThrow<TOptions> = TOptions extends {
+  shouldThrow: infer TShouldThrow extends boolean
+}
+  ? TShouldThrow
+  : true
+
+/**
+ * @internal
+ */
+export type InferSelected<TOptions> = TOptions extends {
+  select: (...args: Array<any>) => infer TSelected
+}
+  ? TSelected
+  : unknown
+
+export type ValidateUseSearchResult<
+  TOptions,
+  TRouter extends AnyRouter = RegisteredRouter,
+> = UseSearchResult<
+  TRouter,
+  InferFrom<TOptions>,
+  InferStrict<TOptions>,
+  InferSelected<TOptions>
+>
+
+export type ValidateUseParamsResult<
+  TOptions,
+  TRouter extends AnyRouter = RegisteredRouter,
+> = Constrain<
+  TOptions,
+  UseParamsResult<
+    TRouter,
+    InferFrom<TOptions>,
+    InferStrict<TOptions>,
+    InferSelected<TOptions>
+  >
+>