@tanstack/react-router 1.20.0 → 1.20.3-alpha.1

package/src/link.tsx

@@ -1,386 +1,64 @@
 import * as React from 'react'
-import { useMatch } from './Matches'
-import { useRouterState } from './useRouterState'
-import { useRouter } from './useRouter'
-import { Trim } from './fileRoute'
-import { AnyRoute, ReactNode, RootSearchSchema } from './route'
-import { RouteByPath, RoutePaths, RoutePathsAutoComplete } from './routeInfo'
-import { RegisteredRouter } from './router'
+import { flushSync } from 'react-dom'
 import {
-  Expand,
-  IsUnion,
-  MakeDifferenceOptional,
-  NoInfer,
-  NonNullableUpdater,
-  PickRequired,
-  Updater,
-  WithoutEmpty,
   deepEqual,
+  exactPathTest,
   functionalUpdate,
-} from './utils'
-import { HistoryState } from '@tanstack/history'
-
-export type CleanPath<T extends string> = T extends `${infer L}//${infer R}`
-  ? CleanPath<`${CleanPath<L>}/${CleanPath<R>}`>
-  : T extends `${infer L}//`
-    ? `${CleanPath<L>}/`
-    : T extends `//${infer L}`
-      ? `/${CleanPath<L>}`
-      : T
-
-export type Split<S, TIncludeTrailingSlash = true> = S extends unknown
-  ? string extends S
-    ? string[]
-    : S extends string
-      ? CleanPath<S> extends ''
-        ? []
-        : TIncludeTrailingSlash extends true
-          ? CleanPath<S> extends `${infer T}/`
-            ? [...Split<T>, '/']
-            : CleanPath<S> extends `/${infer U}`
-              ? Split<U>
-              : CleanPath<S> extends `${infer T}/${infer U}`
-                ? [...Split<T>, ...Split<U>]
-                : [S]
-          : CleanPath<S> extends `${infer T}/${infer U}`
-            ? [...Split<T>, ...Split<U>]
-            : S extends string
-              ? [S]
-              : never
-      : never
-  : never
-
-export type ParsePathParams<T extends string> = keyof {
-  [K in Trim<Split<T>[number], '_'> as K extends `$${infer L}`
-    ? L extends ''
-      ? '_splat'
-      : L
-    : never]: K
-}
-
-export type Join<T, Delimiter extends string = '/'> = T extends []
-  ? ''
-  : T extends [infer L extends string]
-    ? L
-    : T extends [infer L extends string, ...infer Tail extends [...string[]]]
-      ? CleanPath<`${L}${Delimiter}${Join<Tail>}`>
-      : never
-
-export type Last<T extends any[]> = T extends [...infer _, infer L] ? L : never
-
-export type RemoveTrailingSlashes<T> = T extends `${infer R}/`
-  ? RemoveTrailingSlashes<R>
-  : T
-
-export type RemoveLeadingSlashes<T> = T extends `/${infer R}`
-  ? RemoveLeadingSlashes<R>
-  : T
-
-export type SearchPaths<
-  TPaths,
-  TSearchPath extends string,
-> = TPaths extends `${TSearchPath}/${infer TRest}` ? TRest : never
-
-export type SearchRelativePathAutoComplete<
-  TTo extends string,
-  TSearchPath extends string,
-  TPaths,
-  SearchedPaths = SearchPaths<TPaths, TSearchPath>,
-> = SearchedPaths extends string ? `${TTo}/${SearchedPaths}` : never
-
-export type RelativeToParentPathAutoComplete<
-  TFrom extends string,
-  TTo extends string,
-  TPaths,
-  TResolvedPath extends string = RemoveTrailingSlashes<
-    ResolveRelativePath<TFrom, TTo>
-  >,
-> =
-  | SearchRelativePathAutoComplete<TTo, TResolvedPath, TPaths>
-  | (TResolvedPath extends '' ? never : `${TTo}/../`)
-
-export type RelativeToCurrentPathAutoComplete<
-  TFrom extends string,
-  TTo extends string,
-  TRestTo extends string,
-  TPaths,
-  TResolvedPath extends
-    string = RemoveTrailingSlashes<`${RemoveTrailingSlashes<TFrom>}/${RemoveLeadingSlashes<TRestTo>}`>,
-> = SearchRelativePathAutoComplete<TTo, TResolvedPath, TPaths>
-
-export type AbsolutePathAutoComplete<TFrom extends string, TPaths> =
-  | (string extends TFrom
-      ? './'
-      : TFrom extends `/`
-        ? never
-        : SearchPaths<
-              TPaths,
-              RemoveTrailingSlashes<TFrom>
-            > extends infer SearchedPaths
-          ? SearchedPaths extends ''
-            ? never
-            : './'
-          : never)
-  | (string extends TFrom ? '../' : TFrom extends `/` ? never : '../')
-  | TPaths
-
-export type RelativeToPathAutoComplete<
-  TRouteTree extends AnyRoute,
-  TFrom extends string,
-  TTo extends string,
-  TPaths = RoutePaths<TRouteTree>,
-> = TTo extends `..${string}`
-  ? RelativeToParentPathAutoComplete<TFrom, RemoveTrailingSlashes<TTo>, TPaths>
-  : TTo extends `./${infer TRestTTo}`
-    ? RelativeToCurrentPathAutoComplete<
-        TFrom,
-        RemoveTrailingSlashes<TTo>,
-        TRestTTo,
-        TPaths
-      >
-    : AbsolutePathAutoComplete<TFrom, TPaths>
-
-export type NavigateOptions<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
-  TFrom extends RoutePaths<TRouteTree> | string = string,
-  TTo extends string = '',
-  TMaskFrom extends RoutePaths<TRouteTree> | string = TFrom,
-  TMaskTo extends string = '',
-> = ToOptions<TRouteTree, TFrom, TTo, TMaskFrom, TMaskTo> & {
-  // `replace` is a boolean that determines whether the navigation should replace the current history entry or push a new one.
-  replace?: boolean
-  resetScroll?: boolean
-  // If set to `true`, the link's underlying navigate() call will be wrapped in a `React.startTransition` call. Defaults to `true`.
-  startTransition?: boolean
-}
-
-export type ToOptions<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
-  TFrom extends RoutePaths<TRouteTree> | string = string,
-  TTo extends string = '',
-  TMaskFrom extends RoutePaths<TRouteTree> | string = TFrom,
-  TMaskTo extends string = '',
-> = ToSubOptions<TRouteTree, TFrom, TTo> & {
-  mask?: ToMaskOptions<TRouteTree, TMaskFrom, TMaskTo>
-}
-
-export type ToMaskOptions<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
-  TMaskFrom extends RoutePaths<TRouteTree> | string = string,
-  TMaskTo extends string = '',
-> = ToSubOptions<TRouteTree, TMaskFrom, TMaskTo> & {
-  unmaskOnReload?: boolean
-}
-
-export type ToSubOptions<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
-  TFrom extends RoutePaths<TRouteTree> | string = string,
-  TTo extends string = '',
-> = {
-  to?: ToPathOption<TRouteTree, TFrom, TTo>
-  hash?: true | Updater<string>
-  state?: true | NonNullableUpdater<HistoryState>
-  // The source route path. This is automatically set when using route-level APIs, but for type-safe relative routing on the router itself, this is required
-  from?: RoutePathsAutoComplete<TRouteTree, TFrom>
-  // // When using relative route paths, this option forces resolution from the current path, instead of the route API's path or `from` path
-} & CheckPath<TRouteTree, {}, TFrom, TTo> &
-  SearchParamOptions<TRouteTree, TFrom, TTo> &
-  PathParamOptions<TRouteTree, TFrom, TTo>
-
-type ParamsReducer<TFrom, TTo> = TTo | ((current: TFrom) => TTo)
-
-type ParamVariant = 'PATH' | 'SEARCH'
-type ExcludeRootSearchSchema<T, Excluded = Exclude<T, RootSearchSchema>> = [
-  Excluded,
-] extends [never]
-  ? {}
-  : Excluded
-
-export type ResolveRoute<
-  TRouteTree extends AnyRoute,
-  TFrom,
-  TTo,
-  TPath = RemoveTrailingSlashes<
-    string extends TTo ? TFrom : ResolveRelativePath<TFrom, TTo>
-  >,
-> =
-  RouteByPath<TRouteTree, `${TPath & string}/`> extends never
-    ? RouteByPath<TRouteTree, TPath>
-    : RouteByPath<TRouteTree, `${TPath & string}/`>
-
-type PostProcessParams<
-  T,
-  TParamVariant extends ParamVariant,
-> = TParamVariant extends 'SEARCH' ? ExcludeRootSearchSchema<T> : T
-
-export type ParamOptions<
-  TRouteTree extends AnyRoute,
-  TFrom,
-  TTo extends string,
-  TParamVariant extends ParamVariant,
-  TFromRouteType extends
-    | 'allParams'
-    | 'fullSearchSchema' = TParamVariant extends 'PATH'
-    ? 'allParams'
-    : 'fullSearchSchema',
-  TToRouteType extends
-    | 'allParams'
-    | 'fullSearchSchemaInput' = TParamVariant extends 'PATH'
-    ? 'allParams'
-    : 'fullSearchSchemaInput',
-  TFromParams = PostProcessParams<
-    RouteByPath<TRouteTree, TFrom>['types'][TFromRouteType],
-    TParamVariant
-  >,
-  TToParams = PostProcessParams<
-    ResolveRoute<TRouteTree, TFrom, TTo>['types'][TToRouteType],
-    TParamVariant
-  >,
-  TRelativeToParams = TParamVariant extends 'SEARCH'
-    ? TToParams
-    : true extends IsUnion<TFromParams>
-      ? TToParams
-      : MakeDifferenceOptional<TFromParams, TToParams>,
-  TReducer = ParamsReducer<TFromParams, TRelativeToParams>,
-> =
-  Expand<WithoutEmpty<PickRequired<TRelativeToParams>>> extends never
-    ? Partial<MakeParamOption<TParamVariant, true | TReducer>>
-    : TFromParams extends Expand<WithoutEmpty<PickRequired<TRelativeToParams>>>
-      ? MakeParamOption<TParamVariant, true | TReducer>
-      : MakeParamOption<TParamVariant, TReducer>
-
-type MakeParamOption<
-  TParamVariant extends ParamVariant,
-  T,
-> = TParamVariant extends 'PATH'
-  ? MakePathParamOptions<T>
-  : MakeSearchParamOptions<T>
-type MakeSearchParamOptions<T> = { search: T }
-type MakePathParamOptions<T> = { params: T }
-
-export type SearchParamOptions<
-  TRouteTree extends AnyRoute,
-  TFrom,
-  TTo extends string,
-> = ParamOptions<TRouteTree, TFrom, TTo, 'SEARCH'>
-
-export type PathParamOptions<
-  TRouteTree extends AnyRoute,
-  TFrom,
-  TTo extends string,
-> = ParamOptions<TRouteTree, TFrom, TTo, 'PATH'>
-
-export type ToPathOption<
-  TRouteTree extends AnyRoute = AnyRoute,
-  TFrom extends RoutePaths<TRouteTree> | string = string,
-  TTo extends string = '',
-> =
-  | TTo
-  | RelativeToPathAutoComplete<
-      TRouteTree,
-      NoInfer<TFrom> extends string ? NoInfer<TFrom> : '',
-      NoInfer<TTo> & string
-    >
-
-export interface ActiveOptions {
-  exact?: boolean
-  includeHash?: boolean
-  includeSearch?: boolean
-}
-
-export type LinkOptions<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
-  TFrom extends RoutePaths<TRouteTree> | string = string,
-  TTo extends string = '',
-  TMaskFrom extends RoutePaths<TRouteTree> | string = TFrom,
-  TMaskTo extends string = '',
-> = NavigateOptions<TRouteTree, TFrom, TTo, TMaskFrom, TMaskTo> & {
-  // The standard anchor tag target attribute
-  target?: HTMLAnchorElement['target']
-  // Defaults to `{ exact: false, includeHash: false }`
-  activeOptions?: ActiveOptions
-  // If set, will preload the linked route on hover and cache it for this many milliseconds in hopes that the user will eventually navigate there.
-  preload?: false | 'intent'
-  // Delay intent preloading by this many milliseconds. If the intent exits before this delay, the preload will be cancelled.
-  preloadDelay?: number
-  // If true, will render the link without the href attribute
-  disabled?: boolean
-}
-
-export type CheckPath<TRouteTree extends AnyRoute, TPass, TFrom, TTo> =
-  ResolveRoute<TRouteTree, TFrom, TTo> extends never
-    ? string extends TFrom
-      ? RemoveTrailingSlashes<TTo> extends '.' | '..'
-        ? TPass
-        : CheckPathError<TRouteTree>
-      : CheckPathError<TRouteTree>
-    : TPass
-
-export type CheckPathError<TRouteTree extends AnyRoute> = {
-  to: RoutePaths<TRouteTree>
-}
+  preloadWarning,
+  removeTrailingSlash,
+} from '@tanstack/router-core'
+import { useRouterState } from './useRouterState'
+import { useRouter } from './useRouter'
 
-export type ResolveRelativePath<TFrom, TTo = '.'> = TFrom extends string
-  ? TTo extends string
-    ? TTo extends '.'
-      ? TFrom
-      : TTo extends `./`
-        ? Join<[TFrom, '/']>
-        : TTo extends `./${infer TRest}`
-          ? ResolveRelativePath<TFrom, TRest>
-          : TTo extends `/${infer TRest}`
-            ? TTo
-            : Split<TTo> extends ['..', ...infer ToRest]
-              ? Split<TFrom> extends [...infer FromRest, infer FromTail]
-                ? ToRest extends ['/']
-                  ? Join<['/', ...FromRest, '/']>
-                  : ResolveRelativePath<Join<FromRest>, Join<ToRest>>
-                : never
-              : Split<TTo> extends ['.', ...infer ToRest]
-                ? ToRest extends ['/']
-                  ? Join<[TFrom, '/']>
-                  : ResolveRelativePath<TFrom, Join<ToRest>>
-                : CleanPath<Join<['/', ...Split<TFrom>, ...Split<TTo>]>>
-    : never
-  : never
-
-type LinkCurrentTargetElement = {
-  preloadTimeout?: null | ReturnType<typeof setTimeout>
-}
+import {
+  useForwardedRef,
+  useIntersectionObserver,
+  useLayoutEffect,
+} from './utils'
 
-const preloadWarning = 'Error preloading route! ☝️'
+import { useMatches } from './Matches'
+import type {
+  AnyRouter,
+  Constrain,
+  LinkCurrentTargetElement,
+  LinkOptions,
+  RegisteredRouter,
+  RoutePaths,
+} from '@tanstack/router-core'
+import type { ReactNode } from 'react'
+import type {
+  ValidateLinkOptions,
+  ValidateLinkOptionsArray,
+} from './typePrimitives'
 
 export function useLinkProps<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
-  TFrom extends RoutePaths<TRouteTree> | string = string,
-  TTo extends string = '',
-  TMaskFrom extends RoutePaths<TRouteTree> | string = TFrom,
-  TMaskTo extends string = '',
+  TRouter extends AnyRouter = RegisteredRouter,
+  const TFrom extends string = string,
+  const TTo extends string | undefined = undefined,
+  const TMaskFrom extends string = TFrom,
+  const TMaskTo extends string = '',
 >(
-  options: UseLinkPropsOptions<TRouteTree, TFrom, TTo, TMaskFrom, TMaskTo>,
-): React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  options: UseLinkPropsOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>,
+  forwardedRef?: React.ForwardedRef<Element>,
+): React.ComponentPropsWithRef<'a'> {
   const router = useRouter()
-  const matchPathname = useMatch({
-    strict: false,
-    select: (s) => s.pathname,
-  })
+  const [isTransitioning, setIsTransitioning] = React.useState(false)
+  const hasRenderFetched = React.useRef(false)
+  const innerRef = useForwardedRef(forwardedRef)
 
   const {
     // custom props
     activeProps = () => ({ className: 'active' }),
     inactiveProps = () => ({}),
     activeOptions,
-    hash,
-    search,
-    params,
     to,
-    state,
-    mask,
     preload: userPreload,
     preloadDelay: userPreloadDelay,
+    hashScrollIntoView,
     replace,
     startTransition,
     resetScroll,
+    viewTransition,
     // element props
     children,
     target,
@@ -392,72 +70,159 @@ export function useLinkProps<
     onMouseEnter,
     onMouseLeave,
     onTouchStart,
+    ignoreBlocker,
     ...rest
   } = options
 
+  const {
+    // prevent these from being returned
+    params: _params,
+    search: _search,
+    hash: _hash,
+    state: _state,
+    mask: _mask,
+    reloadDocument: _reloadDocument,
+    ...propsSafeToSpread
+  } = rest
+
   // If this link simply reloads the current route,
   // make sure it has a new key so it will trigger a data refresh
 
   // If this `to` is a valid external URL, return
   // null for LinkUtils
 
-  const dest = {
-    from: options.to ? matchPathname : undefined,
-    ...options,
-  }
+  const type: 'internal' | 'external' = React.useMemo(() => {
+    try {
+      new URL(`${to}`)
+      return 'external'
+    } catch {}
+    return 'internal'
+  }, [to])
+
+  // subscribe to search params to re-build location if it changes
+  const currentSearch = useRouterState({
+    select: (s) => s.location.search,
+    structuralSharing: true as any,
+  })
 
-  let type: 'internal' | 'external' = 'internal'
+  // when `from` is not supplied, use the leaf route of the current matches as the `from` location
+  // so relative routing works as expected
+  const from = useMatches({
+    select: (matches) => options.from ?? matches[matches.length - 1]?.fullPath,
+  })
+  // Use it as the default `from` location
+  const _options = React.useMemo(() => ({ ...options, from }), [options, from])
 
-  try {
-    new URL(`${to}`)
-    type = 'external'
-  } catch {}
+  const next = React.useMemo(
+    () => router.buildLocation(_options as any),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [router, _options, currentSearch],
+  )
 
-  const next = router.buildLocation(dest as any)
-  const preload = userPreload ?? router.options.defaultPreload
+  const preload = React.useMemo(() => {
+    if (_options.reloadDocument) {
+      return false
+    }
+    return userPreload ?? router.options.defaultPreload
+  }, [router.options.defaultPreload, userPreload, _options.reloadDocument])
   const preloadDelay =
     userPreloadDelay ?? router.options.defaultPreloadDelay ?? 0
 
   const isActive = useRouterState({
     select: (s) => {
-      // Compare path/hash for matches
-      const currentPathSplit = s.location.pathname.split('/')
-      const nextPathSplit = next.pathname.split('/')
-      const pathIsFuzzyEqual = nextPathSplit.every(
-        (d, i) => d === currentPathSplit[i],
-      )
-      // Combine the matches based on user router.options
-      const pathTest = activeOptions?.exact
-        ? s.location.pathname === next.pathname
-        : pathIsFuzzyEqual
-      const hashTest = activeOptions?.includeHash
-        ? s.location.hash === next.hash
-        : true
-      const searchTest =
-        activeOptions?.includeSearch ?? true
-          ? deepEqual(s.location.search, next.search, !activeOptions?.exact)
-          : true
-
-      // The final "active" test
-      return pathTest && hashTest && searchTest
+      if (activeOptions?.exact) {
+        const testExact = exactPathTest(
+          s.location.pathname,
+          next.pathname,
+          router.basepath,
+        )
+        if (!testExact) {
+          return false
+        }
+      } else {
+        const currentPathSplit = removeTrailingSlash(
+          s.location.pathname,
+          router.basepath,
+        ).split('/')
+        const nextPathSplit = removeTrailingSlash(
+          next.pathname,
+          router.basepath,
+        ).split('/')
+
+        const pathIsFuzzyEqual = nextPathSplit.every(
+          (d, i) => d === currentPathSplit[i],
+        )
+        if (!pathIsFuzzyEqual) {
+          return false
+        }
+      }
+
+      if (activeOptions?.includeSearch ?? true) {
+        const searchTest = deepEqual(s.location.search, next.search, {
+          partial: !activeOptions?.exact,
+          ignoreUndefined: !activeOptions?.explicitUndefined,
+        })
+        if (!searchTest) {
+          return false
+        }
+      }
+
+      if (activeOptions?.includeHash) {
+        return s.location.hash === next.hash
+      }
+      return true
     },
   })
 
+  const doPreload = React.useCallback(() => {
+    router.preloadRoute(_options as any).catch((err) => {
+      console.warn(err)
+      console.warn(preloadWarning)
+    })
+  }, [_options, router])
+
+  const preloadViewportIoCallback = React.useCallback(
+    (entry: IntersectionObserverEntry | undefined) => {
+      if (entry?.isIntersecting) {
+        doPreload()
+      }
+    },
+    [doPreload],
+  )
+
+  useIntersectionObserver(
+    innerRef,
+    preloadViewportIoCallback,
+    { rootMargin: '100px' },
+    { disabled: !!disabled || !(preload === 'viewport') },
+  )
+
+  useLayoutEffect(() => {
+    if (hasRenderFetched.current) {
+      return
+    }
+    if (!disabled && preload === 'render') {
+      doPreload()
+      hasRenderFetched.current = true
+    }
+  }, [disabled, doPreload, preload])
+
   if (type === 'external') {
     return {
-      ...rest,
+      ...propsSafeToSpread,
+      ref: innerRef as React.ComponentPropsWithRef<'a'>['ref'],
       type,
       href: to,
-      children,
-      target,
-      disabled,
-      style,
-      className,
-      onClick,
-      onFocus,
-      onMouseEnter,
-      onMouseLeave,
-      onTouchStart,
+      ...(children && { children }),
+      ...(target && { target }),
+      ...(disabled && { disabled }),
+      ...(style && { style }),
+      ...(className && { className }),
+      ...(onClick && { onClick }),
+      ...(onFocus && { onFocus }),
+      ...(onMouseEnter && { onMouseEnter }),
+      ...(onMouseLeave && { onMouseLeave }),
+      ...(onTouchStart && { onTouchStart }),
     }
   }
 
@@ -472,22 +237,31 @@ export function useLinkProps<
     ) {
       e.preventDefault()
 
-      // All is well? Navigate!
-      router.commitLocation({ ...next, replace, resetScroll, startTransition })
-    }
-  }
+      flushSync(() => {
+        setIsTransitioning(true)
+      })
 
-  const doPreload = () => {
-    React.startTransition(() => {
-      router.preloadRoute(dest as any).catch((err) => {
-        console.warn(err)
-        console.warn(preloadWarning)
+      const unsub = router.subscribe('onResolved', () => {
+        unsub()
+        setIsTransitioning(false)
       })
-    })
+
+      // All is well? Navigate!
+      // N.B. we don't call `router.commitLocation(next) here because we want to run `validateSearch` before committing
+      return router.navigate({
+        ..._options,
+        replace,
+        resetScroll,
+        hashScrollIntoView,
+        startTransition,
+        viewTransition,
+        ignoreBlocker,
+      } as any)
+    }
   }
 
   // The click handler
-  const handleFocus = (e: MouseEvent) => {
+  const handleFocus = (_: MouseEvent) => {
     if (disabled) return
     if (preload) {
       doPreload()
@@ -498,15 +272,15 @@ export function useLinkProps<
 
   const handleEnter = (e: MouseEvent) => {
     if (disabled) return
-    const target = (e.target || {}) as LinkCurrentTargetElement
+    const eventTarget = (e.target || {}) as LinkCurrentTargetElement
 
     if (preload) {
-      if (target.preloadTimeout) {
+      if (eventTarget.preloadTimeout) {
         return
       }
 
-      target.preloadTimeout = setTimeout(() => {
-        target.preloadTimeout = null
+      eventTarget.preloadTimeout = setTimeout(() => {
+        eventTarget.preloadTimeout = null
         doPreload()
       }, preloadDelay)
     }
@@ -514,18 +288,18 @@ export function useLinkProps<
 
   const handleLeave = (e: MouseEvent) => {
     if (disabled) return
-    const target = (e.target || {}) as LinkCurrentTargetElement
+    const eventTarget = (e.target || {}) as LinkCurrentTargetElement
 
-    if (target.preloadTimeout) {
-      clearTimeout(target.preloadTimeout)
-      target.preloadTimeout = null
+    if (eventTarget.preloadTimeout) {
+      clearTimeout(eventTarget.preloadTimeout)
+      eventTarget.preloadTimeout = null
     }
   }
 
   const composeHandlers =
-    (handlers: (undefined | ((e: any) => void))[]) =>
-    (e: React.SyntheticEvent) => {
-      if (e.persist) e.persist()
+    (handlers: Array<undefined | ((e: any) => void)>) =>
+    (e: { persist?: () => void; defaultPrevented: boolean }) => {
+      e.persist?.()
       handlers.filter(Boolean).forEach((handler) => {
         if (e.defaultPrevented) return
         handler!(e)
@@ -534,143 +308,244 @@ export function useLinkProps<
 
   // Get the active props
   const resolvedActiveProps: React.HTMLAttributes<HTMLAnchorElement> = isActive
-    ? functionalUpdate(activeProps as any, {}) ?? {}
+    ? (functionalUpdate(activeProps as any, {}) ?? {})
     : {}
 
   // Get the inactive props
   const resolvedInactiveProps: React.HTMLAttributes<HTMLAnchorElement> =
-    isActive ? {} : functionalUpdate(inactiveProps, {}) ?? {}
+    isActive ? {} : functionalUpdate(inactiveProps, {})
+
+  const resolvedClassName = [
+    className,
+    resolvedActiveProps.className,
+    resolvedInactiveProps.className,
+  ]
+    .filter(Boolean)
+    .join(' ')
+
+  const resolvedStyle = {
+    ...style,
+    ...resolvedActiveProps.style,
+    ...resolvedInactiveProps.style,
+  }
 
   return {
+    ...propsSafeToSpread,
     ...resolvedActiveProps,
     ...resolvedInactiveProps,
-    ...rest,
     href: disabled
       ? undefined
       : next.maskedLocation
-        ? next.maskedLocation.href
-        : next.href,
+        ? router.history.createHref(next.maskedLocation.href)
+        : router.history.createHref(next.href),
+    ref: innerRef as React.ComponentPropsWithRef<'a'>['ref'],
     onClick: composeHandlers([onClick, handleClick]),
     onFocus: composeHandlers([onFocus, handleFocus]),
     onMouseEnter: composeHandlers([onMouseEnter, handleEnter]),
     onMouseLeave: composeHandlers([onMouseLeave, handleLeave]),
     onTouchStart: composeHandlers([onTouchStart, handleTouchStart]),
+    disabled: !!disabled,
     target,
-    style: {
-      ...style,
-      ...resolvedActiveProps.style,
-      ...resolvedInactiveProps.style,
-    },
-    className:
-      [
-        className,
-        resolvedActiveProps.className,
-        resolvedInactiveProps.className,
-      ]
-        .filter(Boolean)
-        .join(' ') || undefined,
-    ...(disabled
-      ? {
-          role: 'link',
-          'aria-disabled': true,
-        }
-      : undefined),
-    ['data-status']: isActive ? 'active' : undefined,
+    ...(Object.keys(resolvedStyle).length && { style: resolvedStyle }),
+    ...(resolvedClassName && { className: resolvedClassName }),
+    ...(disabled && {
+      role: 'link',
+      'aria-disabled': true,
+    }),
+    ...(isActive && { 'data-status': 'active', 'aria-current': 'page' }),
+    ...(isTransitioning && { 'data-transitioning': 'transitioning' }),
   }
 }
 
+type UseLinkReactProps<TComp> = TComp extends keyof React.JSX.IntrinsicElements
+  ? React.JSX.IntrinsicElements[TComp]
+  : React.PropsWithoutRef<
+      TComp extends React.ComponentType<infer TProps> ? TProps : never
+    > &
+      React.RefAttributes<
+        TComp extends
+          | React.FC<{ ref: infer TRef }>
+          | React.Component<{ ref: infer TRef }>
+          ? TRef
+          : never
+      >
+
 export type UseLinkPropsOptions<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
-  TFrom extends RoutePaths<TRouteTree> | string = string,
-  TTo extends string = '',
-  TMaskFrom extends RoutePaths<TRouteTree> | string = TFrom,
-  TMaskTo extends string = '',
-> = ActiveLinkOptions<TRouteTree, TFrom, TTo, TMaskFrom, TMaskTo> &
-  React.AnchorHTMLAttributes<HTMLAnchorElement>
+  TRouter extends AnyRouter = RegisteredRouter,
+  TFrom extends RoutePaths<TRouter['routeTree']> | string = string,
+  TTo extends string | undefined = '.',
+  TMaskFrom extends RoutePaths<TRouter['routeTree']> | string = TFrom,
+  TMaskTo extends string = '.',
+> = ActiveLinkOptions<'a', TRouter, TFrom, TTo, TMaskFrom, TMaskTo> &
+  UseLinkReactProps<'a'>
 
 export type ActiveLinkOptions<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
-  TFrom extends RoutePaths<TRouteTree> | string = string,
-  TTo extends string = '',
-  TMaskFrom extends RoutePaths<TRouteTree> | string = TFrom,
-  TMaskTo extends string = '',
-> = LinkOptions<TRouteTree, TFrom, TTo, TMaskFrom, TMaskTo> & {
-  // A function that returns additional props for the `active` state of this link. These props override other props passed to the link (`style`'s are merged, `className`'s are concatenated)
-  activeProps?:
-    | React.AnchorHTMLAttributes<HTMLAnchorElement>
-    | (() => React.AnchorHTMLAttributes<HTMLAnchorElement>)
-  // A function that returns additional props for the `inactive` state of this link. These props override other props passed to the link (`style`'s are merged, `className`'s are concatenated)
-  inactiveProps?:
-    | React.AnchorHTMLAttributes<HTMLAnchorElement>
-    | (() => React.AnchorHTMLAttributes<HTMLAnchorElement>)
+  TComp = 'a',
+  TRouter extends AnyRouter = RegisteredRouter,
+  TFrom extends string = string,
+  TTo extends string | undefined = '.',
+  TMaskFrom extends string = TFrom,
+  TMaskTo extends string = '.',
+> = LinkOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo> &
+  ActiveLinkOptionProps<TComp>
+
+type ActiveLinkProps<TComp> = Partial<
+  LinkComponentReactProps<TComp> & {
+    [key: `data-${string}`]: unknown
+  }
+>
+
+export interface ActiveLinkOptionProps<TComp = 'a'> {
+  /**
+   * A function that returns additional props for the `active` state of this link.
+   * These props override other props passed to the link (`style`'s are merged, `className`'s are concatenated)
+   */
+  activeProps?: ActiveLinkProps<TComp> | (() => ActiveLinkProps<TComp>)
+  /**
+   * A function that returns additional props for the `inactive` state of this link.
+   * These props override other props passed to the link (`style`'s are merged, `className`'s are concatenated)
+   */
+  inactiveProps?: ActiveLinkProps<TComp> | (() => ActiveLinkProps<TComp>)
 }
 
 export type LinkProps<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
-  TFrom extends RoutePaths<TRouteTree> | string = string,
-  TTo extends string = '',
-  TMaskFrom extends RoutePaths<TRouteTree> | string = TFrom,
-  TMaskTo extends string = '',
-> = ActiveLinkOptions<TRouteTree, TFrom, TTo, TMaskFrom, TMaskTo> & {
+  TComp = 'a',
+  TRouter extends AnyRouter = RegisteredRouter,
+  TFrom extends string = string,
+  TTo extends string | undefined = '.',
+  TMaskFrom extends string = TFrom,
+  TMaskTo extends string = '.',
+> = ActiveLinkOptions<TComp, TRouter, TFrom, TTo, TMaskFrom, TMaskTo> &
+  LinkPropsChildren
+
+export interface LinkPropsChildren {
   // If a function is passed as a child, it will be given the `isActive` boolean to aid in further styling on the element it returns
   children?:
     | React.ReactNode
-    | ((state: { isActive: boolean }) => React.ReactNode)
+    | ((state: {
+        isActive: boolean
+        isTransitioning: boolean
+      }) => React.ReactNode)
 }
 
-type LinkComponent<TComp> = <
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
-  TFrom extends RoutePaths<TRouteTree> = string,
-  TTo extends string = '',
-  TMaskFrom extends RoutePaths<TRouteTree> = TFrom,
-  TMaskTo extends string = '',
+type LinkComponentReactProps<TComp> = Omit<
+  UseLinkReactProps<TComp>,
+  keyof CreateLinkProps
+>
+
+export type LinkComponentProps<
+  TComp = 'a',
+  TRouter extends AnyRouter = RegisteredRouter,
+  TFrom extends string = string,
+  TTo extends string | undefined = '.',
+  TMaskFrom extends string = TFrom,
+  TMaskTo extends string = '.',
+> = LinkComponentReactProps<TComp> &
+  LinkProps<TComp, TRouter, TFrom, TTo, TMaskFrom, TMaskTo>
+
+export type CreateLinkProps = LinkProps<
+  any,
+  any,
+  string,
+  string,
+  string,
+  string
+>
+
+export type LinkComponent<
+  in out TComp,
+  in out TDefaultFrom extends string = string,
+> = <
+  TRouter extends AnyRouter = RegisteredRouter,
+  const TFrom extends string = TDefaultFrom,
+  const TTo extends string | undefined = undefined,
+  const TMaskFrom extends string = TFrom,
+  const TMaskTo extends string = '',
 >(
-  props: React.PropsWithoutRef<
-    LinkProps<TRouteTree, TFrom, TTo, TMaskFrom, TMaskTo> &
-      (TComp extends React.FC<infer TProps> | React.Component<infer TProps>
-        ? TProps
-        : TComp extends keyof JSX.IntrinsicElements
-          ? Omit<React.HTMLProps<TComp>, 'children' | 'preload'>
-          : never)
-  > &
-    React.RefAttributes<
-      TComp extends
-        | React.FC<{ ref: infer TRef }>
-        | React.Component<{ ref: infer TRef }>
-        ? TRef
-        : TComp extends keyof JSX.IntrinsicElements
-          ? React.ComponentRef<TComp>
-          : never
-    >,
+  props: LinkComponentProps<TComp, TRouter, TFrom, TTo, TMaskFrom, TMaskTo>,
 ) => React.ReactElement
 
-export function createLink<const TComp>(Comp: TComp): LinkComponent<TComp> {
-  return React.forwardRef(function Link(props, ref) {
+export interface LinkComponentRoute<
+  in out TDefaultFrom extends string = string,
+> {
+  defaultFrom: TDefaultFrom
+  <
+    TRouter extends AnyRouter = RegisteredRouter,
+    const TTo extends string | undefined = undefined,
+    const TMaskTo extends string = '',
+  >(
+    props: LinkComponentProps<
+      'a',
+      TRouter,
+      this['defaultFrom'],
+      TTo,
+      this['defaultFrom'],
+      TMaskTo
+    >,
+  ): React.ReactElement
+}
+
+export function createLink<const TComp>(
+  Comp: Constrain<TComp, any, (props: CreateLinkProps) => ReactNode>,
+): LinkComponent<TComp> {
+  return React.forwardRef(function CreatedLink(props, ref) {
     return <Link {...(props as any)} _asChild={Comp} ref={ref} />
   }) as any
 }
 
-export const Link: LinkComponent<'a'> = React.forwardRef((props: any, ref) => {
-  const { _asChild, ...rest } = props
-  const { type, ...linkProps } = useLinkProps(rest as any)
-
-  const children =
-    typeof rest.children === 'function'
-      ? rest.children({
-          isActive: (linkProps as any)['data-status'] === 'active',
-        })
-      : rest.children
+export const Link: LinkComponent<'a'> = React.forwardRef<Element, any>(
+  (props, ref) => {
+    const { _asChild, ...rest } = props
+    const {
+      type: _type,
+      ref: innerRef,
+      ...linkProps
+    } = useLinkProps(rest as any, ref)
+
+    const children =
+      typeof rest.children === 'function'
+        ? rest.children({
+            isActive: (linkProps as any)['data-status'] === 'active',
+          })
+        : rest.children
+
+    if (typeof _asChild === 'undefined') {
+      // the ReturnType of useLinkProps returns the correct type for a <a> element, not a general component that has a disabled prop
+      // @ts-expect-error
+      delete linkProps.disabled
+    }
 
-  return React.createElement(
-    _asChild ? _asChild : 'a',
-    {
-      ...linkProps,
-      ref,
-    },
-    children as any,
-  )
-}) as any
+    return React.createElement(
+      _asChild ? _asChild : 'a',
+      {
+        ...linkProps,
+        ref: innerRef,
+      },
+      children,
+    )
+  },
+) as any
 
 function isCtrlEvent(e: MouseEvent) {
   return !!(e.metaKey || e.altKey || e.ctrlKey || e.shiftKey)
 }
+
+export type LinkOptionsFnOptions<
+  TOptions,
+  TComp,
+  TRouter extends AnyRouter = RegisteredRouter,
+> =
+  TOptions extends ReadonlyArray<any>
+    ? ValidateLinkOptionsArray<TRouter, TOptions, string, TComp>
+    : ValidateLinkOptions<TRouter, TOptions, string, TComp>
+
+export type LinkOptionsFn<TComp> = <
+  const TOptions,
+  TRouter extends AnyRouter = RegisteredRouter,
+>(
+  options: LinkOptionsFnOptions<TOptions, TComp, TRouter>,
+) => TOptions
+
+export const linkOptions: LinkOptionsFn<'a'> = (options) => {
+  return options as any
+}