one 1.2.57 → 1.2.59

package/src/router/router.ts

@@ -35,11 +35,80 @@ import { sortRoutes } from './sortRoutes'
 import { getQualifiedRouteComponent } from './useScreens'
 import { preloadRouteModules } from './useViteRoutes'
 import { getNavigateAction } from './utils/getNavigateAction'
+import {
+  findRouteNodeFromState,
+  extractParamsFromState,
+  extractSearchFromHref,
+  extractPathnameFromHref,
+} from './findRouteNode'
+import {
+  validateParams as runValidateParams,
+  RouteValidationError,
+  ParamValidationError,
+} from '../validateParams'
+import { checkBlocker } from '../useBlocker'
+import { devtoolsRegistry } from '../devtools/registry'
 
 // Module-scoped variables
 export let routeNode: RouteNode | null = null
 export let rootComponent: ComponentType
 
+// Global registry for protected routes
+// Key: contextKey (e.g., '/protected-test'), Value: Set of protected route names
+const protectedRouteRegistry = new Map<string, Set<string>>()
+
+/**
+ * Register protected routes for a navigator context.
+ * Called by navigators when their protectedScreens changes.
+ */
+export function registerProtectedRoutes(
+  contextKey: string,
+  protectedScreens: Set<string>
+) {
+  if (protectedScreens.size === 0) {
+    protectedRouteRegistry.delete(contextKey)
+  } else {
+    protectedRouteRegistry.set(contextKey, protectedScreens)
+  }
+}
+
+/**
+ * Unregister protected routes for a navigator context.
+ * Called when a navigator unmounts.
+ */
+export function unregisterProtectedRoutes(contextKey: string) {
+  protectedRouteRegistry.delete(contextKey)
+}
+
+/**
+ * Check if a route path is protected and should be blocked.
+ * Returns true if the route is protected.
+ */
+export function isRouteProtected(href: string): boolean {
+  // Normalize the href (remove leading/trailing slashes)
+  const normalizedHref = href.replace(/^\/+|\/+$/g, '')
+
+  // Check each navigator context to see if this route is protected
+  for (const [contextKey, protectedScreens] of protectedRouteRegistry) {
+    const normalizedContextKey = contextKey.replace(/^\/+|\/+$/g, '')
+
+    // Check if this href is under this context
+    if (normalizedHref.startsWith(normalizedContextKey)) {
+      // Get the route name relative to this context
+      const relativePath = normalizedHref
+        .slice(normalizedContextKey.length)
+        .replace(/^\//, '')
+      const routeName = relativePath.split('/')[0] || 'index'
+
+      if (protectedScreens.has(routeName)) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
 export let hasAttemptedToHideSplash = false
 export let initialState: OneRouter.ResultState | undefined
 export let rootState: OneRouter.ResultState | undefined
@@ -56,6 +125,60 @@ const rootStateSubscribers = new Set<OneRouter.RootStateListener>()
 const loadingStateSubscribers = new Set<OneRouter.LoadingStateListener>()
 const storeSubscribers = new Set<() => void>()
 
+// Validation state tracking
+export type ValidationState = {
+  status: 'idle' | 'validating' | 'error' | 'valid'
+  error?: Error
+  lastValidatedHref?: string
+}
+
+let validationState: ValidationState = { status: 'idle' }
+const validationStateSubscribers = new Set<(state: ValidationState) => void>()
+
+export function subscribeToValidationState(subscriber: (state: ValidationState) => void) {
+  validationStateSubscribers.add(subscriber)
+  return () => validationStateSubscribers.delete(subscriber)
+}
+
+export function setValidationState(state: ValidationState) {
+  validationState = state
+  for (const subscriber of validationStateSubscribers) {
+    subscriber(state)
+  }
+  // Dispatch event for devtools
+  if (
+    process.env.TAMAGUI_TARGET !== 'native' &&
+    state.status === 'error' &&
+    state.error
+  ) {
+    window.dispatchEvent(
+      new CustomEvent('one-validation-error', {
+        detail: {
+          error: {
+            message: state.error.message,
+            name: state.error.name,
+            stack: state.error.stack,
+          },
+          href: state.lastValidatedHref,
+          timestamp: Date.now(),
+        },
+      })
+    )
+  }
+}
+
+export function getValidationState(): ValidationState {
+  return validationState
+}
+
+export function useValidationState() {
+  return useSyncExternalStore(
+    subscribeToValidationState,
+    getValidationState,
+    getValidationState
+  )
+}
+
 // Initialize function
 export function initialize(
   context: One.RouteContext,
@@ -272,6 +395,23 @@ export function updateState(state: OneRouter.ResultState, nextStateParam = state
     }
     routeInfo = nextRouteInfo
   }
+
+  // Expose devtools API in development
+  if (process.env.NODE_ENV === 'development' && typeof window !== 'undefined') {
+    // Use registry to avoid circular deps - useLoader registers its function there
+    ;(window as any).__oneDevtools = {
+      routeInfo: nextRouteInfo,
+      rootState: state,
+      routeNode,
+      getRoutes: () => routeNode?.children || [],
+      getLoaderTimingHistory: () => devtoolsRegistry.getLoaderTimingHistory?.() ?? [],
+      getPreloadHistory,
+    }
+    // Dispatch event for devtools panels to listen
+    if (process.env.TAMAGUI_TARGET !== 'native') {
+      window.dispatchEvent(new CustomEvent('one-route-change', { detail: nextRouteInfo }))
+    }
+  }
 }
 
 // Subscription functions
@@ -397,6 +537,9 @@ async function doPreload(href: string) {
   const preloadPath = getPreloadPath(href)
   const loaderPath = getLoaderPath(href)
   const cssPreloadPath = getPreloadCSSPath(href)
+
+  recordPreloadStart(href)
+
   try {
     const [_preload, cssPreloadModule, loader] = await Promise.all([
       dynamicImport(preloadPath),
@@ -406,18 +549,24 @@ async function doPreload(href: string) {
     ])
 
     // Store the CSS inject function for later use on navigation
-    if (cssPreloadModule?.injectCSS) {
+    const hasCss = !!cssPreloadModule?.injectCSS
+    if (hasCss) {
       cssInjectFunctions[href] = cssPreloadModule.injectCSS
     }
 
-    if (!loader?.loader) {
+    const hasLoader = !!loader?.loader
+    if (!hasLoader) {
+      recordPreloadComplete(href, false, hasCss)
       return null
     }
 
     const result = await loader.loader()
+    recordPreloadComplete(href, true, hasCss)
     return result ?? null
   } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err)
     console.error(`[one] preload error for ${href}:`, err)
+    recordPreloadError(href, errorMessage)
     return null
   }
 }
@@ -428,6 +577,79 @@ export const preloadedLoaderData: Record<string, any> = {}
 // Store CSS inject functions for calling on navigation
 const cssInjectFunctions: Record<string, (() => Promise<void[]>) | undefined> = {}
 
+// Preload status tracking for devtools
+export type PreloadStatus = 'pending' | 'loading' | 'loaded' | 'error'
+export type PreloadEntry = {
+  href: string
+  status: PreloadStatus
+  startTime: number
+  endTime?: number
+  error?: string
+  hasLoader: boolean
+  hasCss: boolean
+}
+
+const preloadHistory: PreloadEntry[] = []
+const MAX_PRELOAD_HISTORY = 30
+
+// Preload tracking functions - only do work in development for devtools
+function recordPreloadStart(href: string) {
+  if (process.env.NODE_ENV !== 'development') return
+
+  const existing = preloadHistory.find((p) => p.href === href)
+  if (existing) {
+    existing.status = 'loading'
+    existing.startTime = performance.now()
+    return
+  }
+  preloadHistory.unshift({
+    href,
+    status: 'loading',
+    startTime: performance.now(),
+    hasLoader: false,
+    hasCss: false,
+  })
+  if (preloadHistory.length > MAX_PRELOAD_HISTORY) {
+    preloadHistory.pop()
+  }
+  dispatchPreloadEvent()
+}
+
+function recordPreloadComplete(href: string, hasLoader: boolean, hasCss: boolean) {
+  if (process.env.NODE_ENV !== 'development') return
+
+  const entry = preloadHistory.find((p) => p.href === href)
+  if (entry) {
+    entry.status = 'loaded'
+    entry.endTime = performance.now()
+    entry.hasLoader = hasLoader
+    entry.hasCss = hasCss
+  }
+  dispatchPreloadEvent()
+}
+
+function recordPreloadError(href: string, error: string) {
+  if (process.env.NODE_ENV !== 'development') return
+
+  const entry = preloadHistory.find((p) => p.href === href)
+  if (entry) {
+    entry.status = 'error'
+    entry.endTime = performance.now()
+    entry.error = error
+  }
+  dispatchPreloadEvent()
+}
+
+function dispatchPreloadEvent() {
+  if (process.env.TAMAGUI_TARGET !== 'native') {
+    window.dispatchEvent(new CustomEvent('one-preload-update'))
+  }
+}
+
+export function getPreloadHistory(): PreloadEntry[] {
+  return preloadHistory
+}
+
 export function preloadRoute(href: string, injectCSS = false): Promise<any> | undefined {
   if (process.env.TAMAGUI_TARGET === 'native') {
     return
@@ -477,6 +699,16 @@ export async function linkTo(
     return
   }
 
+  // Check if any blocker wants to block this navigation (web only)
+  if (checkBlocker(href, event === 'REPLACE' ? 'replace' : 'push')) {
+    return
+  }
+
+  // Check if the route is protected and should be blocked
+  if (isRouteProtected(href)) {
+    return
+  }
+
   assertIsReady(navigationRef)
   const current = navigationRef.current
 
@@ -540,8 +772,65 @@ export async function linkTo(
 
   setLoadingState('loading')
 
+  // Preload route modules first so loadRoute() won't throw Suspense promises
   await preloadRoute(href, true)
 
+  // Run async route validation before navigation
+  const matchingRouteNode = findRouteNodeFromState(state, routeNode)
+  if (matchingRouteNode?.loadRoute) {
+    setValidationState({ status: 'validating', lastValidatedHref: href })
+
+    try {
+      const loadedRoute = matchingRouteNode.loadRoute()
+      const params = extractParamsFromState(state)
+      const search = extractSearchFromHref(href)
+      const pathname = extractPathnameFromHref(href)
+
+      // Run validateParams if exported
+      if (loadedRoute.validateParams) {
+        runValidateParams(loadedRoute.validateParams, params)
+      }
+
+      // Run validateRoute if exported
+      if (loadedRoute.validateRoute) {
+        const validationResult = await loadedRoute.validateRoute({
+          params,
+          search,
+          pathname,
+          href,
+        })
+
+        // Check for explicit invalid result
+        if (validationResult && !validationResult.valid) {
+          const error = new RouteValidationError(
+            validationResult.error || 'Route validation failed',
+            validationResult.details
+          )
+          setValidationState({ status: 'error', error, lastValidatedHref: href })
+          throw error
+        }
+      }
+
+      setValidationState({ status: 'valid', lastValidatedHref: href })
+    } catch (error) {
+      // Handle Suspense promises thrown by loadRoute in dev mode
+      if (error && typeof (error as any).then === 'function') {
+        // Wait for the route to load and skip validation for this navigation
+        await (error as Promise<any>).catch(() => {})
+        setValidationState({ status: 'valid', lastValidatedHref: href })
+      } else if (
+        error instanceof ParamValidationError ||
+        error instanceof RouteValidationError
+      ) {
+        setValidationState({ status: 'error', error, lastValidatedHref: href })
+        throw error
+      } else {
+        // Re-throw other errors
+        throw error
+      }
+    }
+  }
+
   const rootState = navigationRef.getRootState()
 
   const hash = href.indexOf('#')

package/src/router/useNavigation.ts

@@ -8,9 +8,18 @@ import { getNameFromFilePath } from './matchers'
 import { useContextKey } from './Route'
 
 /**
- * Return the navigation object for the current route.
- * @param parent Provide an absolute path like `/(root)` to the parent route or a relative path like `../../` to the parent route.
- * @returns the navigation object for the provided route.
+ * Returns the React Navigation navigation object for the current route.
+ * Provides low-level access to navigation actions, events, and screen options.
+ *
+ * @param parent - Optional path to parent navigator (absolute like `/(tabs)` or relative like `../`)
+ * @returns The navigation object with methods like setOptions, addListener, getParent
+ * @link https://onestack.dev/docs/api/hooks/useNavigation
+ *
+ * @example
+ * ```tsx
+ * const navigation = useNavigation()
+ * navigation.setOptions({ title: 'My Screen' })
+ * ```
  */
 export function useNavigation<T = NavigationProp<ReactNavigation.RootParamList>>(
   parent?: string

package/src/router/useScreens.tsx

@@ -224,7 +224,11 @@ function getSortedChildren(
  */
 export function useSortedScreens(
   order: ScreenProps[],
-  options?: { onlyMatching?: boolean }
+  options?: {
+    onlyMatching?: boolean
+    /** Set of route names to filter out (protected routes with guard=false) */
+    protectedScreens?: Set<string>
+  }
 ): React.ReactNode[] {
   const node = useRouteNode()
 
@@ -233,8 +237,10 @@ export function useSortedScreens(
       ? getSortedChildren(node.children, order, node.initialRouteName, options)
       : []
 
-    return sorted.map((value) => routeToScreen(value.route, value.props))
-  }, [node?.children, node?.initialRouteName, order])
+    return sorted
+      .filter((value) => !options?.protectedScreens?.has(value.route.route))
+      .map((value) => routeToScreen(value.route, value.props))
+  }, [node?.children, node?.initialRouteName, order, options?.protectedScreens])
 
   return sortedScreens
 }

package/src/useBlocker.native.ts

@@ -0,0 +1,153 @@
+import { useNavigation } from '@react-navigation/native'
+import * as React from 'react'
+
+export type BlockerState = 'unblocked' | 'blocked' | 'proceeding'
+
+export type BlockerFunction = (args: {
+  currentLocation: string
+  nextLocation: string
+  historyAction: 'push' | 'pop' | 'replace'
+}) => boolean
+
+export type Blocker =
+  | {
+      state: 'unblocked'
+      reset?: undefined
+      proceed?: undefined
+      location?: undefined
+    }
+  | {
+      state: 'blocked'
+      reset: () => void
+      proceed: () => void
+      location: string
+    }
+  | {
+      state: 'proceeding'
+      reset?: undefined
+      proceed?: undefined
+      location: string
+    }
+
+/**
+ * Block navigation when a condition is met.
+ *
+ * On native, this uses React Navigation's `beforeRemove` event to prevent navigation.
+ * Note that this only works for navigation within the app - it cannot prevent
+ * the app from being closed or backgrounded.
+ *
+ * @param shouldBlock - Either a boolean or a function that returns whether to block.
+ *
+ * @example
+ * ```tsx
+ * function EditForm() {
+ *   const [isDirty, setIsDirty] = useState(false)
+ *   const blocker = useBlocker(isDirty)
+ *
+ *   return (
+ *     <>
+ *       <TextInput onChange={() => setIsDirty(true)} />
+ *
+ *       {blocker.state === 'blocked' && (
+ *         <Modal>
+ *           <Text>You have unsaved changes. Leave anyway?</Text>
+ *           <Button title="Stay" onPress={blocker.reset} />
+ *           <Button title="Leave" onPress={blocker.proceed} />
+ *         </Modal>
+ *       )}
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export function useBlocker(shouldBlock: BlockerFunction | boolean): Blocker {
+  const navigation = useNavigation()
+  const [state, setState] = React.useState<BlockerState>('unblocked')
+  const [pendingEvent, setPendingEvent] = React.useState<any>(null)
+  const [blockedLocation, setBlockedLocation] = React.useState<string | null>(null)
+
+  const shouldBlockRef = React.useRef(shouldBlock)
+  shouldBlockRef.current = shouldBlock
+
+  React.useEffect(() => {
+    const unsubscribe = navigation.addListener('beforeRemove', (e) => {
+      const currentShouldBlock = shouldBlockRef.current
+
+      // Get the next location from the action payload
+      const payload = e.data?.action?.payload as { name?: string } | undefined
+      const nextLocation = payload?.name || 'previous screen'
+
+      // Determine if we should block
+      const block =
+        typeof currentShouldBlock === 'function'
+          ? currentShouldBlock({
+              currentLocation: '', // Not easily available on native
+              nextLocation,
+              historyAction: 'pop',
+            })
+          : currentShouldBlock
+
+      if (!block) {
+        return
+      }
+
+      // Prevent default behavior (leaving the screen)
+      e.preventDefault()
+
+      // Store the event to dispatch later if user confirms
+      setPendingEvent(e)
+      setBlockedLocation(nextLocation)
+      setState('blocked')
+    })
+
+    return unsubscribe
+  }, [navigation])
+
+  const reset = React.useCallback(() => {
+    setPendingEvent(null)
+    setBlockedLocation(null)
+    setState('unblocked')
+  }, [])
+
+  const proceed = React.useCallback(() => {
+    if (!pendingEvent) return
+
+    setState('proceeding')
+
+    // Dispatch the original action to complete navigation
+    navigation.dispatch(pendingEvent.data.action)
+
+    // Reset after navigation
+    setTimeout(() => {
+      setPendingEvent(null)
+      setBlockedLocation(null)
+      setState('unblocked')
+    }, 100)
+  }, [navigation, pendingEvent])
+
+  if (state === 'unblocked') {
+    return { state: 'unblocked' }
+  }
+
+  if (state === 'proceeding') {
+    return { state: 'proceeding', location: blockedLocation! }
+  }
+
+  return {
+    state: 'blocked',
+    reset,
+    proceed,
+    location: blockedLocation!,
+  }
+}
+
+/**
+ * No-op on native - native uses React Navigation's beforeRemove event instead.
+ * This is only used by the router on web.
+ */
+export function checkBlocker(
+  _nextLocation: string,
+  _historyAction: 'push' | 'pop' | 'replace' = 'push'
+): boolean {
+  return false
+}