From 7c2f75b4cd9268558b69715ca13854aadb7920f4 Mon Sep 17 00:00:00 2001
From: Christopher Menendez <christophermenendezmorales@gmail.com>
Date: Thu, 9 Oct 2025 16:35:07 +1100
Subject: [PATCH] docs(history): clarify blockerFn boolean contract

---
 .../framework/react/api/router/useBlockerHook.md      |  2 +-
 packages/history/src/index.ts                         | 11 +++++++++--
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/router/framework/react/api/router/useBlockerHook.md b/docs/router/framework/react/api/router/useBlockerHook.md
index 218efc6b4a2..4999321e467 100644
--- a/docs/router/framework/react/api/router/useBlockerHook.md
+++ b/docs/router/framework/react/api/router/useBlockerHook.md
@@ -57,7 +57,7 @@ type ShouldBlockFnArgs = {
 
 - Optional
 - Type: `BlockerFn`
-- The function that returns a `boolean` or `Promise<boolean>` indicating whether to allow navigation.
+- The function that returns a `boolean` or `Promise<boolean>` indicating whether the navigation should be blocked (`true` blocks, `false` allows).
 
 ### `options.condition` option (⚠️ deprecated)
 
diff --git a/packages/history/src/index.ts b/packages/history/src/index.ts
index 3178cb90bbf..602aa0c2ac0 100644
--- a/packages/history/src/index.ts
+++ b/packages/history/src/index.ts
@@ -58,7 +58,12 @@ export type ParsedHistoryState = HistoryState & {
   __TSR_index: number
 }
 
-type ShouldAllowNavigation = any
+export type ShouldBlockNavigation = boolean
+
+/**
+ * @deprecated Use `ShouldBlockNavigation`. Returning `true` blocks navigation.
+ */
+export type ShouldAllowNavigation = ShouldBlockNavigation
 
 export type HistoryAction = 'PUSH' | 'REPLACE' | 'FORWARD' | 'BACK' | 'GO'
 
@@ -70,7 +75,7 @@ export type BlockerFnArgs = {
 
 export type BlockerFn = (
   args: BlockerFnArgs,
-) => Promise<ShouldAllowNavigation> | ShouldAllowNavigation
+) => Promise<ShouldBlockNavigation> | ShouldBlockNavigation
 
 export type NavigationBlocker = {
   blockerFn: BlockerFn
@@ -149,6 +154,7 @@ export function createHistory(opts: {
           action: actionInfo.type,
         })
         if (isBlocked) {
+          // Truthy means the blocker wants to keep the navigation from proceeding.
           opts.onBlocked?.()
           return
         }
@@ -437,6 +443,7 @@ export function createBrowserHistory(opts?: {
             action,
           })
           if (isBlocked) {
+            // Truthy means the blocker wants to keep the navigation from proceeding.
             ignoreNextPop = true
             win.history.go(1)
             history.notify(notify)