@depup/tanstack__react-router 1.166.4-depup.0

package/src/Match.tsx

@@ -0,0 +1,360 @@
+import * as React from 'react'
+import invariant from 'tiny-invariant'
+import warning from 'tiny-warning'
+import {
+  createControlledPromise,
+  getLocationChangeInfo,
+  isNotFound,
+  isRedirect,
+  rootRouteId,
+} from '@tanstack/router-core'
+import { isServer } from '@tanstack/router-core/isServer'
+import { CatchBoundary, ErrorComponent } from './CatchBoundary'
+import { useRouterState } from './useRouterState'
+import { useRouter } from './useRouter'
+import { CatchNotFound } from './not-found'
+import { matchContext } from './matchContext'
+import { SafeFragment } from './SafeFragment'
+import { renderRouteNotFound } from './renderRouteNotFound'
+import { ScrollRestoration } from './scroll-restoration'
+import { ClientOnly } from './ClientOnly'
+import type {
+  AnyRoute,
+  ParsedLocation,
+  RootRouteOptions,
+} from '@tanstack/router-core'
+
+export const Match = React.memo(function MatchImpl({
+  matchId,
+}: {
+  matchId: string
+}) {
+  const router = useRouter()
+  const matchState = useRouterState({
+    select: (s) => {
+      const matchIndex = s.matches.findIndex((d) => d.id === matchId)
+      const match = s.matches[matchIndex]
+      invariant(
+        match,
+        `Could not find match for matchId "${matchId}". Please file an issue!`,
+      )
+      return {
+        routeId: match.routeId,
+        ssr: match.ssr,
+        _displayPending: match._displayPending,
+        resetKey: s.loadedAt,
+        parentRouteId: s.matches[matchIndex - 1]?.routeId as string,
+      }
+    },
+    structuralSharing: true as any,
+  })
+
+  const route: AnyRoute = router.routesById[matchState.routeId]
+
+  const PendingComponent =
+    route.options.pendingComponent ?? router.options.defaultPendingComponent
+
+  const pendingElement = PendingComponent ? <PendingComponent /> : null
+
+  const routeErrorComponent =
+    route.options.errorComponent ?? router.options.defaultErrorComponent
+
+  const routeOnCatch = route.options.onCatch ?? router.options.defaultOnCatch
+
+  const routeNotFoundComponent = route.isRoot
+    ? // If it's the root route, use the globalNotFound option, with fallback to the notFoundRoute's component
+      (route.options.notFoundComponent ??
+      router.options.notFoundRoute?.options.component)
+    : route.options.notFoundComponent
+
+  const resolvedNoSsr =
+    matchState.ssr === false || matchState.ssr === 'data-only'
+  const ResolvedSuspenseBoundary =
+    // If we're on the root route, allow forcefully wrapping in suspense
+    (!route.isRoot || route.options.wrapInSuspense || resolvedNoSsr) &&
+    (route.options.wrapInSuspense ??
+      PendingComponent ??
+      ((route.options.errorComponent as any)?.preload || resolvedNoSsr))
+      ? React.Suspense
+      : SafeFragment
+
+  const ResolvedCatchBoundary = routeErrorComponent
+    ? CatchBoundary
+    : SafeFragment
+
+  const ResolvedNotFoundBoundary = routeNotFoundComponent
+    ? CatchNotFound
+    : SafeFragment
+
+  const ShellComponent = route.isRoot
+    ? ((route.options as RootRouteOptions).shellComponent ?? SafeFragment)
+    : SafeFragment
+  return (
+    <ShellComponent>
+      <matchContext.Provider value={matchId}>
+        <ResolvedSuspenseBoundary fallback={pendingElement}>
+          <ResolvedCatchBoundary
+            getResetKey={() => matchState.resetKey}
+            errorComponent={routeErrorComponent || ErrorComponent}
+            onCatch={(error, errorInfo) => {
+              // Forward not found errors (we don't want to show the error component for these)
+              if (isNotFound(error)) throw error
+              warning(false, `Error in route match: ${matchId}`)
+              routeOnCatch?.(error, errorInfo)
+            }}
+          >
+            <ResolvedNotFoundBoundary
+              fallback={(error) => {
+                // If the current not found handler doesn't exist or it has a
+                // route ID which doesn't match the current route, rethrow the error
+                if (
+                  !routeNotFoundComponent ||
+                  (error.routeId && error.routeId !== matchState.routeId) ||
+                  (!error.routeId && !route.isRoot)
+                )
+                  throw error
+
+                return React.createElement(routeNotFoundComponent, error as any)
+              }}
+            >
+              {resolvedNoSsr || matchState._displayPending ? (
+                <ClientOnly fallback={pendingElement}>
+                  <MatchInner matchId={matchId} />
+                </ClientOnly>
+              ) : (
+                <MatchInner matchId={matchId} />
+              )}
+            </ResolvedNotFoundBoundary>
+          </ResolvedCatchBoundary>
+        </ResolvedSuspenseBoundary>
+      </matchContext.Provider>
+      {matchState.parentRouteId === rootRouteId &&
+      router.options.scrollRestoration ? (
+        <>
+          <OnRendered />
+          <ScrollRestoration />
+        </>
+      ) : null}
+    </ShellComponent>
+  )
+})
+
+// On Rendered can't happen above the root layout because it actually
+// renders a dummy dom element to track the rendered state of the app.
+// We render a script tag with a key that changes based on the current
+// location state.__TSR_key. Also, because it's below the root layout, it
+// allows us to fire onRendered events even after a hydration mismatch
+// error that occurred above the root layout (like bad head/link tags,
+// which is common).
+function OnRendered() {
+  const router = useRouter()
+
+  const prevLocationRef = React.useRef<undefined | ParsedLocation<{}>>(
+    undefined,
+  )
+
+  return (
+    <script
+      key={router.latestLocation.state.__TSR_key}
+      suppressHydrationWarning
+      ref={(el) => {
+        if (
+          el &&
+          (prevLocationRef.current === undefined ||
+            prevLocationRef.current.href !== router.latestLocation.href)
+        ) {
+          router.emit({
+            type: 'onRendered',
+            ...getLocationChangeInfo(router.state),
+          })
+          prevLocationRef.current = router.latestLocation
+        }
+      }}
+    />
+  )
+}
+
+export const MatchInner = React.memo(function MatchInnerImpl({
+  matchId,
+}: {
+  matchId: string
+}): any {
+  const router = useRouter()
+
+  const { match, key, routeId } = useRouterState({
+    select: (s) => {
+      const match = s.matches.find((d) => d.id === matchId)!
+      const routeId = match.routeId as string
+
+      const remountFn =
+        (router.routesById[routeId] as AnyRoute).options.remountDeps ??
+        router.options.defaultRemountDeps
+      const remountDeps = remountFn?.({
+        routeId,
+        loaderDeps: match.loaderDeps,
+        params: match._strictParams,
+        search: match._strictSearch,
+      })
+      const key = remountDeps ? JSON.stringify(remountDeps) : undefined
+
+      return {
+        key,
+        routeId,
+        match: {
+          id: match.id,
+          status: match.status,
+          error: match.error,
+          invalid: match.invalid,
+          _forcePending: match._forcePending,
+          _displayPending: match._displayPending,
+        },
+      }
+    },
+    structuralSharing: true as any,
+  })
+
+  const route = router.routesById[routeId] as AnyRoute
+
+  const out = React.useMemo(() => {
+    const Comp = route.options.component ?? router.options.defaultComponent
+    if (Comp) {
+      return <Comp key={key} />
+    }
+    return <Outlet />
+  }, [key, route.options.component, router.options.defaultComponent])
+
+  if (match._displayPending) {
+    throw router.getMatch(match.id)?._nonReactive.displayPendingPromise
+  }
+
+  if (match._forcePending) {
+    throw router.getMatch(match.id)?._nonReactive.minPendingPromise
+  }
+
+  // see also hydrate() in packages/router-core/src/ssr/ssr-client.ts
+  if (match.status === 'pending') {
+    // We're pending, and if we have a minPendingMs, we need to wait for it
+    const pendingMinMs =
+      route.options.pendingMinMs ?? router.options.defaultPendingMinMs
+    if (pendingMinMs) {
+      const routerMatch = router.getMatch(match.id)
+      if (routerMatch && !routerMatch._nonReactive.minPendingPromise) {
+        // Create a promise that will resolve after the minPendingMs
+        if (!(isServer ?? router.isServer)) {
+          const minPendingPromise = createControlledPromise<void>()
+
+          routerMatch._nonReactive.minPendingPromise = minPendingPromise
+
+          setTimeout(() => {
+            minPendingPromise.resolve()
+            // We've handled the minPendingPromise, so we can delete it
+            routerMatch._nonReactive.minPendingPromise = undefined
+          }, pendingMinMs)
+        }
+      }
+    }
+    throw router.getMatch(match.id)?._nonReactive.loadPromise
+  }
+
+  if (match.status === 'notFound') {
+    invariant(isNotFound(match.error), 'Expected a notFound error')
+    return renderRouteNotFound(router, route, match.error)
+  }
+
+  if (match.status === 'redirected') {
+    // Redirects should be handled by the router transition. If we happen to
+    // encounter a redirect here, it's a bug. Let's warn, but render nothing.
+    invariant(isRedirect(match.error), 'Expected a redirect error')
+
+    // warning(
+    //   false,
+    //   'Tried to render a redirected route match! This is a weird circumstance, please file an issue!',
+    // )
+    throw router.getMatch(match.id)?._nonReactive.loadPromise
+  }
+
+  if (match.status === 'error') {
+    // If we're on the server, we need to use React's new and super
+    // wonky api for throwing errors from a server side render inside
+    // of a suspense boundary. This is the only way to get
+    // renderToPipeableStream to not hang indefinitely.
+    // We'll serialize the error and rethrow it on the client.
+    if (isServer ?? router.isServer) {
+      const RouteErrorComponent =
+        (route.options.errorComponent ??
+          router.options.defaultErrorComponent) ||
+        ErrorComponent
+      return (
+        <RouteErrorComponent
+          error={match.error as any}
+          reset={undefined as any}
+          info={{
+            componentStack: '',
+          }}
+        />
+      )
+    }
+
+    throw match.error
+  }
+
+  return out
+})
+
+/**
+ * Render the next child match in the route tree. Typically used inside
+ * a route component to render nested routes.
+ *
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/outletComponent
+ */
+export const Outlet = React.memo(function OutletImpl() {
+  const router = useRouter()
+  const matchId = React.useContext(matchContext)
+  const routeId = useRouterState({
+    select: (s) => s.matches.find((d) => d.id === matchId)?.routeId as string,
+  })
+
+  const route = router.routesById[routeId]!
+
+  const parentGlobalNotFound = useRouterState({
+    select: (s) => {
+      const matches = s.matches
+      const parentMatch = matches.find((d) => d.id === matchId)
+      invariant(
+        parentMatch,
+        `Could not find parent match for matchId "${matchId}"`,
+      )
+      return parentMatch.globalNotFound
+    },
+  })
+
+  const childMatchId = useRouterState({
+    select: (s) => {
+      const matches = s.matches
+      const index = matches.findIndex((d) => d.id === matchId)
+      return matches[index + 1]?.id
+    },
+  })
+
+  const pendingElement = router.options.defaultPendingComponent ? (
+    <router.options.defaultPendingComponent />
+  ) : null
+
+  if (parentGlobalNotFound) {
+    return renderRouteNotFound(router, route, undefined)
+  }
+
+  if (!childMatchId) {
+    return null
+  }
+
+  const nextMatch = <Match matchId={childMatchId} />
+
+  if (routeId === rootRouteId) {
+    return (
+      <React.Suspense fallback={pendingElement}>{nextMatch}</React.Suspense>
+    )
+  }
+
+  return nextMatch
+})

package/src/Matches.tsx

@@ -0,0 +1,313 @@
+import * as React from 'react'
+import warning from 'tiny-warning'
+import { rootRouteId } from '@tanstack/router-core'
+import { isServer } from '@tanstack/router-core/isServer'
+import { CatchBoundary, ErrorComponent } from './CatchBoundary'
+import { useRouterState } from './useRouterState'
+import { useRouter } from './useRouter'
+import { Transitioner } from './Transitioner'
+import { matchContext } from './matchContext'
+import { Match } from './Match'
+import { SafeFragment } from './SafeFragment'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
+import type {
+  AnyRoute,
+  AnyRouter,
+  DeepPartial,
+  Expand,
+  MakeOptionalPathParams,
+  MakeOptionalSearchParams,
+  MakeRouteMatchUnion,
+  MaskOptions,
+  MatchRouteOptions,
+  NoInfer,
+  RegisteredRouter,
+  ResolveRelativePath,
+  ResolveRoute,
+  RouteByPath,
+  RouterState,
+  ToSubOptionsProps,
+} from '@tanstack/router-core'
+
+declare module '@tanstack/router-core' {
+  export interface RouteMatchExtensions {
+    meta?: Array<React.JSX.IntrinsicElements['meta'] | undefined>
+    links?: Array<React.JSX.IntrinsicElements['link'] | undefined>
+    scripts?: Array<React.JSX.IntrinsicElements['script'] | undefined>
+    styles?: Array<React.JSX.IntrinsicElements['style'] | undefined>
+    headScripts?: Array<React.JSX.IntrinsicElements['script'] | undefined>
+  }
+}
+
+/**
+ * Internal component that renders the router's active match tree with
+ * suspense, error, and not-found boundaries. Rendered by `RouterProvider`.
+ */
+export function Matches() {
+  const router = useRouter()
+  const rootRoute: AnyRoute = router.routesById[rootRouteId]
+
+  const PendingComponent =
+    rootRoute.options.pendingComponent ?? router.options.defaultPendingComponent
+
+  const pendingElement = PendingComponent ? <PendingComponent /> : null
+
+  // Do not render a root Suspense during SSR or hydrating from SSR
+  const ResolvedSuspense =
+    (isServer ?? router.isServer) ||
+    (typeof document !== 'undefined' && router.ssr)
+      ? SafeFragment
+      : React.Suspense
+
+  const inner = (
+    <ResolvedSuspense fallback={pendingElement}>
+      {!(isServer ?? router.isServer) && <Transitioner />}
+      <MatchesInner />
+    </ResolvedSuspense>
+  )
+
+  return router.options.InnerWrap ? (
+    <router.options.InnerWrap>{inner}</router.options.InnerWrap>
+  ) : (
+    inner
+  )
+}
+
+function MatchesInner() {
+  const router = useRouter()
+  const matchId = useRouterState({
+    select: (s) => {
+      return s.matches[0]?.id
+    },
+  })
+
+  const resetKey = useRouterState({
+    select: (s) => s.loadedAt,
+  })
+
+  const matchComponent = matchId ? <Match matchId={matchId} /> : null
+
+  return (
+    <matchContext.Provider value={matchId}>
+      {router.options.disableGlobalCatchBoundary ? (
+        matchComponent
+      ) : (
+        <CatchBoundary
+          getResetKey={() => resetKey}
+          errorComponent={ErrorComponent}
+          onCatch={
+            process.env.NODE_ENV !== 'production'
+              ? (error) => {
+                  warning(
+                    false,
+                    `The following error wasn't caught by any route! At the very least, consider setting an 'errorComponent' in your RootRoute!`,
+                  )
+                  warning(false, error.message || error.toString())
+                }
+              : undefined
+          }
+        >
+          {matchComponent}
+        </CatchBoundary>
+      )}
+    </matchContext.Provider>
+  )
+}
+
+export type UseMatchRouteOptions<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TFrom extends string = string,
+  TTo extends string | undefined = undefined,
+  TMaskFrom extends string = TFrom,
+  TMaskTo extends string = '',
+> = ToSubOptionsProps<TRouter, TFrom, TTo> &
+  DeepPartial<MakeOptionalSearchParams<TRouter, TFrom, TTo>> &
+  DeepPartial<MakeOptionalPathParams<TRouter, TFrom, TTo>> &
+  MaskOptions<TRouter, TMaskFrom, TMaskTo> &
+  MatchRouteOptions
+
+/**
+ * Create a matcher function for testing locations against route definitions.
+ *
+ * The returned function accepts standard navigation options (`to`, `params`,
+ * `search`, etc.) and returns either `false` (no match) or the matched params
+ * object when the route matches the current or pending location.
+ *
+ * Useful for conditional rendering and active UI states.
+ *
+ * @returns A `matchRoute(options)` function that returns `false` or params.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useMatchRouteHook
+ */
+export function useMatchRoute<TRouter extends AnyRouter = RegisteredRouter>() {
+  const router = useRouter()
+
+  useRouterState({
+    select: (s) => [s.location.href, s.resolvedLocation?.href, s.status],
+    structuralSharing: true as any,
+  })
+
+  return React.useCallback(
+    <
+      const TFrom extends string = string,
+      const TTo extends string | undefined = undefined,
+      const TMaskFrom extends string = TFrom,
+      const TMaskTo extends string = '',
+    >(
+      opts: UseMatchRouteOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>,
+    ):
+      | false
+      | Expand<ResolveRoute<TRouter, TFrom, TTo>['types']['allParams']> => {
+      const { pending, caseSensitive, fuzzy, includeSearch, ...rest } = opts
+
+      return router.matchRoute(rest as any, {
+        pending,
+        caseSensitive,
+        fuzzy,
+        includeSearch,
+      })
+    },
+    [router],
+  )
+}
+
+export type MakeMatchRouteOptions<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TFrom extends string = string,
+  TTo extends string | undefined = undefined,
+  TMaskFrom extends string = TFrom,
+  TMaskTo extends string = '',
+> = UseMatchRouteOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo> & {
+  // 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?:
+    | ((
+        params?: RouteByPath<
+          TRouter['routeTree'],
+          ResolveRelativePath<TFrom, NoInfer<TTo>>
+        >['types']['allParams'],
+      ) => React.ReactNode)
+    | React.ReactNode
+}
+
+/**
+ * Component that conditionally renders its children based on whether a route
+ * matches the provided `from`/`to` options. If `children` is a function, it
+ * receives the matched params object.
+ *
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/matchRouteComponent
+ */
+export function MatchRoute<
+  TRouter extends AnyRouter = RegisteredRouter,
+  const TFrom extends string = string,
+  const TTo extends string | undefined = undefined,
+  const TMaskFrom extends string = TFrom,
+  const TMaskTo extends string = '',
+>(props: MakeMatchRouteOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>): any {
+  const matchRoute = useMatchRoute()
+  const params = matchRoute(props as any) as boolean
+
+  if (typeof props.children === 'function') {
+    return (props.children as any)(params)
+  }
+
+  return params ? props.children : null
+}
+
+export interface UseMatchesBaseOptions<
+  TRouter extends AnyRouter,
+  TSelected,
+  TStructuralSharing,
+> {
+  select?: (
+    matches: Array<MakeRouteMatchUnion<TRouter>>,
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
+}
+
+export type UseMatchesResult<
+  TRouter extends AnyRouter,
+  TSelected,
+> = unknown extends TSelected ? Array<MakeRouteMatchUnion<TRouter>> : TSelected
+
+export function useMatches<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseMatchesBaseOptions<TRouter, TSelected, TStructuralSharing> &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+): UseMatchesResult<TRouter, TSelected> {
+  return useRouterState({
+    select: (state: RouterState<TRouter['routeTree']>) => {
+      const matches = state.matches
+      return opts?.select
+        ? opts.select(matches as Array<MakeRouteMatchUnion<TRouter>>)
+        : matches
+    },
+    structuralSharing: opts?.structuralSharing,
+  } as any) as UseMatchesResult<TRouter, TSelected>
+}
+
+/**
+ * Read the full array of active route matches or select a derived subset.
+ *
+ * Useful for debugging, breadcrumbs, or aggregating metadata across matches.
+ *
+ * @returns The array of matches (or the selected value).
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useMatchesHook
+ */
+
+/**
+ * Read the full array of active route matches or select a derived subset.
+ *
+ * Useful for debugging, breadcrumbs, or aggregating metadata across matches.
+ *
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useMatchesHook
+ */
+export function useParentMatches<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseMatchesBaseOptions<TRouter, TSelected, TStructuralSharing> &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+): UseMatchesResult<TRouter, TSelected> {
+  const contextMatchId = React.useContext(matchContext)
+
+  return useMatches({
+    select: (matches: Array<MakeRouteMatchUnion<TRouter>>) => {
+      matches = matches.slice(
+        0,
+        matches.findIndex((d) => d.id === contextMatchId),
+      )
+      return opts?.select ? opts.select(matches) : matches
+    },
+    structuralSharing: opts?.structuralSharing,
+  } as any)
+}
+
+/**
+ * Read the array of active route matches that are children of the current
+ * match (or selected parent) in the match tree.
+ */
+export function useChildMatches<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseMatchesBaseOptions<TRouter, TSelected, TStructuralSharing> &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+): UseMatchesResult<TRouter, TSelected> {
+  const contextMatchId = React.useContext(matchContext)
+
+  return useMatches({
+    select: (matches: Array<MakeRouteMatchUnion<TRouter>>) => {
+      matches = matches.slice(
+        matches.findIndex((d) => d.id === contextMatchId) + 1,
+      )
+      return opts?.select ? opts.select(matches) : matches
+    },
+    structuralSharing: opts?.structuralSharing,
+  } as any)
+}