@tanstack/router-core 0.0.1-beta.9 → 1.20.3-alpha.1

package/src/scroll-restoration.ts

@@ -0,0 +1,340 @@
+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
+      })
+    }
+  })
+}
+
+/**
+ * @internal
+ * 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
+ */
+export function handleHashScroll(router: AnyRouter) {
+  if (typeof document !== 'undefined' && (document as any).querySelector) {
+    const hashScrollIntoViewOptions =
+      router.state.location.state.__hashScrollIntoViewOptions ?? true
+
+    if (hashScrollIntoViewOptions && router.state.location.hash !== '') {
+      const el = document.getElementById(router.state.location.hash)
+      if (el) {
+        el.scrollIntoView(hashScrollIntoViewOptions)
+      }
+    }
+  }
+}

package/src/searchMiddleware.ts

@@ -0,0 +1,54 @@
+import { deepEqual } from './utils'
+import type { NoInfer, PickOptional } from './utils'
+import type { SearchMiddleware } from './route'
+import type { IsRequiredParams } from './link'
+
+export function retainSearchParams<TSearchSchema extends object>(
+  keys: Array<keyof TSearchSchema> | true,
+): SearchMiddleware<TSearchSchema> {
+  return ({ search, next }) => {
+    const result = next(search)
+    if (keys === true) {
+      return { ...search, ...result }
+    }
+    // add missing keys from search to result
+    keys.forEach((key) => {
+      if (!(key in result)) {
+        result[key] = search[key]
+      }
+    })
+    return result
+  }
+}
+
+export function stripSearchParams<
+  TSearchSchema,
+  TOptionalProps = PickOptional<NoInfer<TSearchSchema>>,
+  const TValues =
+    | Partial<NoInfer<TOptionalProps>>
+    | Array<keyof TOptionalProps>,
+  const TInput = IsRequiredParams<TSearchSchema> extends never
+    ? TValues | true
+    : TValues,
+>(input: NoInfer<TInput>): SearchMiddleware<TSearchSchema> {
+  return ({ search, next }) => {
+    if (input === true) {
+      return {}
+    }
+    const result = next(search) as Record<string, unknown>
+    if (Array.isArray(input)) {
+      input.forEach((key) => {
+        delete result[key]
+      })
+    } else {
+      Object.entries(input as Record<string, unknown>).forEach(
+        ([key, value]) => {
+          if (deepEqual(result[key], value)) {
+            delete result[key]
+          }
+        },
+      )
+    }
+    return result as any
+  }
+}

package/src/searchParams.ts

@@ -1,19 +1,22 @@
 import { decode, encode } from './qss'
-import { AnySearchSchema } from './routeConfig'
+import type { AnySchema } from './validators'
 
 export const defaultParseSearch = parseSearchWith(JSON.parse)
-export const defaultStringifySearch = stringifySearchWith(JSON.stringify)
+export const defaultStringifySearch = stringifySearchWith(
+  JSON.stringify,
+  JSON.parse,
+)
 
 export function parseSearchWith(parser: (str: string) => any) {
-  return (searchStr: string): AnySearchSchema => {
+  return (searchStr: string): AnySchema => {
     if (searchStr.substring(0, 1) === '?') {
       searchStr = searchStr.substring(1)
     }
 
-    let query: Record<string, unknown> = decode(searchStr)
+    const query: Record<string, unknown> = decode(searchStr)
 
     // Try to parse any query params that might be json
-    for (let key in query) {
+    for (const key in query) {
       const value = query[key]
       if (typeof value === 'string') {
         try {
@@ -28,27 +31,47 @@ export function parseSearchWith(parser: (str: string) => any) {
   }
 }
 
-export function stringifySearchWith(stringify: (search: any) => string) {
+export function stringifySearchWith(
+  stringify: (search: any) => string,
+  parser?: (str: string) => any,
+) {
+  function stringifyValue(val: any) {
+    if (typeof val === 'object' && val !== null) {
+      try {
+        return stringify(val)
+      } catch (err) {
+        // silent
+      }
+    } else if (typeof val === 'string' && typeof parser === 'function') {
+      try {
+        // Check if it's a valid parseable string.
+        // If it is, then stringify it again.
+        parser(val)
+        return stringify(val)
+      } catch (err) {
+        // silent
+      }
+    }
+    return val
+  }
+
   return (search: Record<string, any>) => {
     search = { ...search }
 
-    if (search) {
-      Object.keys(search).forEach((key) => {
-        const val = search[key]
-        if (typeof val === 'undefined' || val === undefined) {
-          delete search[key]
-        } else if (val && typeof val === 'object' && val !== null) {
-          try {
-            search[key] = stringify(val)
-          } catch (err) {
-            // silent
-          }
-        }
-      })
-    }
+    Object.keys(search).forEach((key) => {
+      const val = search[key]
+      if (typeof val === 'undefined' || val === undefined) {
+        delete search[key]
+      } else {
+        search[key] = stringifyValue(val)
+      }
+    })
 
     const searchStr = encode(search as Record<string, string>).toString()
 
     return searchStr ? `?${searchStr}` : ''
   }
 }
+
+export type SearchSerializer = (searchObj: Record<string, any>) => string
+export type SearchParser = (searchStr: string) => Record<string, any>

package/src/serializer.ts

@@ -0,0 +1,32 @@
+export interface StartSerializer {
+  stringify: (obj: unknown) => string
+  parse: (str: string) => unknown
+  encode: <T>(value: T) => T
+  decode: <T>(value: T) => T
+}
+
+export type SerializerStringifyBy<T, TSerializable> = T extends TSerializable
+  ? T
+  : T extends (...args: Array<any>) => any
+    ? 'Function is not serializable'
+    : { [K in keyof T]: SerializerStringifyBy<T[K], TSerializable> }
+
+export type SerializerParseBy<T, TSerializable> = T extends TSerializable
+  ? T
+  : unknown extends SerializerExtensions['ReadableStream']
+    ? { [K in keyof T]: SerializerParseBy<T[K], TSerializable> }
+    : T extends SerializerExtensions['ReadableStream']
+      ? ReadableStream
+      : { [K in keyof T]: SerializerParseBy<T[K], TSerializable> }
+
+export interface DefaultSerializerExtensions {
+  ReadableStream: unknown
+}
+
+export interface SerializerExtensions extends DefaultSerializerExtensions {}
+
+export type Serializable = Date | undefined | Error | FormData | bigint
+
+export type SerializerStringify<T> = SerializerStringifyBy<T, Serializable>
+
+export type SerializerParse<T> = SerializerParseBy<T, Serializable>

package/src/structuralSharing.ts

@@ -0,0 +1,7 @@
+import type { Constrain } from './utils'
+
+export interface OptionalStructuralSharing<TStructuralSharing, TConstraint> {
+  readonly structuralSharing?:
+    | Constrain<TStructuralSharing, TConstraint>
+    | undefined
+}

package/src/typePrimitives.ts

@@ -0,0 +1,181 @@
+import type {
+  FromPathOption,
+  NavigateOptions,
+  PathParamOptions,
+  SearchParamOptions,
+  ToPathOption,
+} from './link'
+import type { RedirectOptions } 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,
+  RedirectOptions<
+    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>
+  >
+>