@tanstack/react-router 1.89.2 → 1.91.0

package/src/useBlocker.tsx

@@ -1,92 +1,296 @@
 import * as React from 'react'
 import { useRouter } from './useRouter'
-import type { BlockerFn } from '@tanstack/history'
-import type { ReactNode } from './route'
+import type {
+  BlockerFnArgs,
+  HistoryAction,
+  HistoryLocation,
+} from '@tanstack/history'
+import type { AnyRoute } from './route'
+import type { ParseRoute } from './routeInfo'
+import type { AnyRouter, RegisteredRouter } from './router'
 
-type BlockerResolver = {
-  status: 'idle' | 'blocked'
-  proceed: () => void
-  reset: () => void
+interface ShouldBlockFnLocation<
+  out TRouteId,
+  out TFullPath,
+  out TAllParams,
+  out TFullSearchSchema,
+> {
+  routeId: TRouteId
+  fullPath: TFullPath
+  pathname: string
+  params: TAllParams
+  search: TFullSearchSchema
 }
 
-type BlockerOpts = {
-  blockerFn?: BlockerFn
+type AnyShouldBlockFnLocation = ShouldBlockFnLocation<any, any, any, any>
+type MakeShouldBlockFnLocationUnion<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TRoute extends AnyRoute = ParseRoute<TRouter['routeTree']>,
+> = TRoute extends any
+  ? ShouldBlockFnLocation<
+      TRoute['id'],
+      TRoute['fullPath'],
+      TRoute['types']['allParams'],
+      TRoute['types']['fullSearchSchema']
+    >
+  : never
+
+type BlockerResolver<TRouter extends AnyRouter = RegisteredRouter> =
+  | {
+      status: 'blocked'
+      current: MakeShouldBlockFnLocationUnion<TRouter>
+      next: MakeShouldBlockFnLocationUnion<TRouter>
+      action: HistoryAction
+      proceed: () => void
+      reset: () => void
+    }
+  | {
+      status: 'idle'
+      current: undefined
+      next: undefined
+      action: undefined
+      proceed: undefined
+      reset: undefined
+    }
+
+type ShouldBlockFnArgs<TRouter extends AnyRouter = RegisteredRouter> = {
+  current: MakeShouldBlockFnLocationUnion<TRouter>
+  next: MakeShouldBlockFnLocationUnion<TRouter>
+  action: HistoryAction
+}
+
+export type ShouldBlockFn<TRouter extends AnyRouter = RegisteredRouter> = (
+  args: ShouldBlockFnArgs<TRouter>,
+) => boolean | Promise<boolean>
+export type UseBlockerOpts<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TWithResolver extends boolean = boolean,
+> = {
+  shouldBlockFn: ShouldBlockFn<TRouter>
+  enableBeforeUnload?: boolean | (() => boolean)
+  disabled?: boolean
+  withResolver?: TWithResolver
+}
+
+type LegacyBlockerFn = () => Promise<any> | any
+type LegacyBlockerOpts = {
+  blockerFn?: LegacyBlockerFn
   condition?: boolean | any
 }
 
-export function useBlocker(blockerFnOrOpts?: BlockerOpts): BlockerResolver
+function _resolveBlockerOpts(
+  opts?: UseBlockerOpts | LegacyBlockerOpts | LegacyBlockerFn,
+  condition?: boolean | any,
+): UseBlockerOpts {
+  if (opts === undefined) {
+    return {
+      shouldBlockFn: () => true,
+      withResolver: false,
+    }
+  }
+
+  if ('shouldBlockFn' in opts) {
+    return opts
+  }
+
+  if (typeof opts === 'function') {
+    const shouldBlock = Boolean(condition ?? true)
+
+    const _customBlockerFn = async () => {
+      if (shouldBlock) return await opts()
+      return false
+    }
+
+    return {
+      shouldBlockFn: _customBlockerFn,
+      enableBeforeUnload: shouldBlock,
+      withResolver: false,
+    }
+  }
+
+  const shouldBlock = Boolean(opts.condition ?? true)
+  const fn = opts.blockerFn
+
+  const _customBlockerFn = async () => {
+    if (shouldBlock && fn !== undefined) {
+      return await fn()
+    }
+    return shouldBlock
+  }
+
+  return {
+    shouldBlockFn: _customBlockerFn,
+    enableBeforeUnload: shouldBlock,
+    withResolver: fn === undefined,
+  }
+}
+
+export function useBlocker<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TWithResolver extends boolean = false,
+>(
+  opts: UseBlockerOpts<TRouter, TWithResolver>,
+): TWithResolver extends true ? BlockerResolver<TRouter> : void
+
+/**
+ * @deprecated Use the shouldBlockFn property instead
+ */
+export function useBlocker(blockerFnOrOpts?: LegacyBlockerOpts): BlockerResolver
 
 /**
- * @deprecated Use the BlockerOpts object syntax instead
+ * @deprecated Use the UseBlockerOpts object syntax instead
  */
 export function useBlocker(
-  blockerFn?: BlockerFn,
+  blockerFn?: LegacyBlockerFn,
   condition?: boolean | any,
 ): BlockerResolver
 
 export function useBlocker(
-  blockerFnOrOpts?: BlockerFn | BlockerOpts,
+  opts?: UseBlockerOpts | LegacyBlockerOpts | LegacyBlockerFn,
   condition?: boolean | any,
-): BlockerResolver {
-  const { blockerFn, blockerCondition } = blockerFnOrOpts
-    ? typeof blockerFnOrOpts === 'function'
-      ? { blockerFn: blockerFnOrOpts, blockerCondition: condition ?? true }
-      : {
-          blockerFn: blockerFnOrOpts.blockerFn,
-          blockerCondition: blockerFnOrOpts.condition ?? true,
-        }
-    : { blockerFn: undefined, blockerCondition: condition ?? true }
-  const { history } = useRouter()
+): BlockerResolver | void {
+  const {
+    shouldBlockFn,
+    enableBeforeUnload = true,
+    disabled = false,
+    withResolver = false,
+  } = _resolveBlockerOpts(opts, condition)
+
+  const router = useRouter()
+  const { history } = router
 
   const [resolver, setResolver] = React.useState<BlockerResolver>({
     status: 'idle',
-    proceed: () => {},
-    reset: () => {},
+    current: undefined,
+    next: undefined,
+    action: undefined,
+    proceed: undefined,
+    reset: undefined,
   })
 
   React.useEffect(() => {
-    const blockerFnComposed = async () => {
-      // If a function is provided, it takes precedence over the promise blocker
-      if (blockerFn) {
-        return await blockerFn()
+    const blockerFnComposed = async (blockerFnArgs: BlockerFnArgs) => {
+      function getLocation(
+        location: HistoryLocation,
+      ): AnyShouldBlockFnLocation {
+        const parsedLocation = router.parseLocation(undefined, location)
+        const matchedRoutes = router.getMatchedRoutes(parsedLocation)
+        if (matchedRoutes.foundRoute === undefined) {
+          throw new Error(`No route found for location ${location.href}`)
+        }
+        return {
+          routeId: matchedRoutes.foundRoute.id,
+          fullPath: matchedRoutes.foundRoute.fullPath,
+          pathname: parsedLocation.pathname,
+          params: matchedRoutes.routeParams,
+          search: parsedLocation.search,
+        }
+      }
+
+      const current = getLocation(blockerFnArgs.currentLocation)
+      const next = getLocation(blockerFnArgs.nextLocation)
+
+      const shouldBlock = await shouldBlockFn({
+        action: blockerFnArgs.action,
+        current,
+        next,
+      })
+      if (!withResolver) {
+        return shouldBlock
+      }
+
+      if (!shouldBlock) {
+        return false
       }
 
       const promise = new Promise<boolean>((resolve) => {
         setResolver({
           status: 'blocked',
-          proceed: () => resolve(true),
-          reset: () => resolve(false),
+          current,
+          next,
+          action: blockerFnArgs.action,
+          proceed: () => resolve(false),
+          reset: () => resolve(true),
         })
       })
 
       const canNavigateAsync = await promise
-
       setResolver({
         status: 'idle',
-        proceed: () => {},
-        reset: () => {},
+        current: undefined,
+        next: undefined,
+        action: undefined,
+        proceed: undefined,
+        reset: undefined,
       })
 
       return canNavigateAsync
     }
 
-    return !blockerCondition ? undefined : history.block(blockerFnComposed)
-  }, [blockerFn, blockerCondition, history])
+    return disabled
+      ? undefined
+      : history.block({ blockerFn: blockerFnComposed, enableBeforeUnload })
+  }, [shouldBlockFn, enableBeforeUnload, disabled, withResolver, history])
 
   return resolver
 }
 
-export function Block({ blockerFn, condition, children }: PromptProps) {
-  const resolver = useBlocker({ blockerFn, condition })
+const _resolvePromptBlockerArgs = (
+  props: PromptProps | LegacyPromptProps,
+): UseBlockerOpts => {
+  if ('shouldBlockFn' in props) {
+    return { ...props }
+  }
+
+  const shouldBlock = Boolean(props.condition ?? true)
+  const fn = props.blockerFn
+
+  const _customBlockerFn = async () => {
+    if (shouldBlock && fn !== undefined) {
+      return await fn()
+    }
+    return shouldBlock
+  }
+
+  return {
+    shouldBlockFn: _customBlockerFn,
+    enableBeforeUnload: shouldBlock,
+    withResolver: fn === undefined,
+  }
+}
+
+export function Block<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TWithResolver extends boolean = boolean,
+>(opts: PromptProps<TRouter, TWithResolver>): React.ReactNode
+
+/**
+ *  @deprecated Use the UseBlockerOpts property instead
+ */
+export function Block(opts: LegacyPromptProps): React.ReactNode
+
+export function Block(opts: PromptProps | LegacyPromptProps): React.ReactNode {
+  const { children, ...rest } = opts
+  const args = _resolvePromptBlockerArgs(rest)
+
+  const resolver = useBlocker(args)
   return children
     ? typeof children === 'function'
-      ? children(resolver)
+      ? children(resolver as any)
       : children
     : null
 }
 
-export type PromptProps = {
-  blockerFn?: BlockerFn
+type LegacyPromptProps = {
+  blockerFn?: LegacyBlockerFn
   condition?: boolean | any
-  children?: ReactNode | (({ proceed, reset }: BlockerResolver) => ReactNode)
+  children?: React.ReactNode | ((params: BlockerResolver) => React.ReactNode)
+}
+
+type PromptProps<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TWithResolver extends boolean = boolean,
+  TParams = TWithResolver extends true ? BlockerResolver<TRouter> : void,
+> = UseBlockerOpts<TRouter, TWithResolver> & {
+  children?: React.ReactNode | ((params: TParams) => React.ReactNode)
 }

package/src/utils.ts

@@ -111,6 +111,14 @@ export type PartialMergeAll<TUnion> =
   | ExtractPrimitives<TUnion>
   | PartialMergeAllObject<TUnion>
 
+export type Constrain<T, TConstraint, TDefault = TConstraint> =
+  | (T extends TConstraint ? T : never)
+  | TDefault
+
+export type ConstrainLiteral<T, TConstraint, TDefault = TConstraint> =
+  | (T & TConstraint)
+  | TDefault
+
 /**
  * To be added to router types
  */
@@ -139,10 +147,6 @@ export type MergeAll<TUnion> =
   | MergeAllObjects<TUnion>
   | ExtractPrimitives<TUnion>
 
-export type Constrain<T, TConstraint, TDefault = TConstraint> =
-  | (T extends TConstraint ? T : never)
-  | TDefault
-
 export type ValidateJSON<T> = ((...args: Array<any>) => any) extends T
   ? unknown extends T
     ? never
@@ -359,7 +363,7 @@ export type StrictOrFrom<
       strict: TStrict
     }
   : {
-      from: StringLiteral<Constrain<TFrom, RouteIds<TRouter['routeTree']>>>
+      from: ConstrainLiteral<TFrom, RouteIds<TRouter['routeTree']>>
       strict?: TStrict
     }