one 1.2.57 → 1.2.58

package/src/fork/createMemoryHistory.tsx

@@ -5,7 +5,9 @@
  * Please refrain from making changes to this file, as it will make merging updates from the upstream harder.
  * All modifications except formatting should be marked with `// @modified` comment.
  *
- * No modifications currently, copied only in order to use a custom `useLinking` function.
+ * Modifications:
+ * - Added displayPath field to HistoryRecord for route masking support
+ * - Modified push() and replace() to accept displayPath parameter for showing masked URLs in browser
  */
 
 import type { NavigationState } from '@react-navigation/core'
@@ -16,8 +18,10 @@ type HistoryRecord = {
   id: string
   // Navigation state object for the history entry
   state: NavigationState
-  // Path of the history entry
+  // Path of the history entry (actual navigation path)
   path: string
+  // @modified - Display path for route masking (URL shown in browser)
+  displayPath?: string
 }
 
 export function createMemoryHistory() {
@@ -70,7 +74,16 @@ export function createMemoryHistory() {
       return -1
     },
 
-    push({ path, state }: { path: string; state: NavigationState }) {
+    // @modified - added displayPath parameter for route masking
+    push({
+      path,
+      state,
+      displayPath,
+    }: {
+      path: string
+      state: NavigationState
+      displayPath?: string
+    }) {
       interrupt()
 
       const id = nanoid()
@@ -79,21 +92,35 @@ export function createMemoryHistory() {
       // So we remove any existing entries after the current index to clean them up
       items = items.slice(0, index + 1)
 
-      items.push({ path, state, id })
+      items.push({ path, state, id, displayPath })
       index = items.length - 1
 
+      // @modified - use displayPath for browser URL if provided (route masking)
+      const urlPath = displayPath ?? path
+
       if (process.env.ONE_DEBUG_ROUTER) {
-        console.info(`[one] 📜 history.push path=${path}`)
+        console.info(
+          `[one] 📜 history.push path=${path}${displayPath ? ` displayPath=${displayPath}` : ''}`
+        )
       }
 
       // We pass empty string for title because it's ignored in all browsers except safari
       // We don't store state object in history.state because:
       // - browsers have limits on how big it can be, and we don't control the size
       // - while not recommended, there could be non-serializable data in state
-      window.history.pushState({ id }, '', path)
+      window.history.pushState({ id }, '', urlPath)
     },
 
-    replace({ path, state }: { path: string; state: NavigationState }) {
+    // @modified - added displayPath parameter for route masking
+    replace({
+      path,
+      state,
+      displayPath,
+    }: {
+      path: string
+      state: NavigationState
+      displayPath?: string
+    }) {
       interrupt()
 
       const id = window.history.state?.id ?? nanoid()
@@ -112,20 +139,25 @@ export function createMemoryHistory() {
         //   So we need to push the entry as there's nothing to replace
 
         pathWithHash = pathWithHash + hash
-        items = [{ path: pathWithHash, state, id }]
+        items = [{ path: pathWithHash, state, id, displayPath }]
         index = 0
       } else {
         if (items[index].path === path) {
           pathWithHash = pathWithHash + hash
         }
-        items[index] = { path, state, id }
+        items[index] = { path, state, id, displayPath }
       }
 
+      // @modified - use displayPath for browser URL if provided (route masking)
+      const urlPath = displayPath ? displayPath + hash : pathWithHash
+
       if (process.env.ONE_DEBUG_ROUTER) {
-        console.info(`[one] 📜 history.replace path=${pathWithHash}`)
+        console.info(
+          `[one] 📜 history.replace path=${pathWithHash}${displayPath ? ` displayPath=${displayPath}` : ''}`
+        )
       }
 
-      window.history.replaceState({ id }, '', pathWithHash)
+      window.history.replaceState({ id }, '', urlPath)
     },
 
     // `history.go(n)` is asynchronous, there are couple of things to keep in mind:

package/src/fork/useLinking.ts

@@ -23,6 +23,7 @@ import * as React from 'react'
 // @modified - start
 // import { ServerContext } from '@react-navigation/web';
 import { rootState as routerRootState } from '../router/router'
+import { stripGroupSegmentsFromPath } from '../router/matchers'
 import { ServerLocationContext } from '../router/serverLocationContext'
 import { createMemoryHistory } from './createMemoryHistory'
 import { appendBaseUrl } from './getPathFromState-mods'
@@ -254,7 +255,9 @@ export function useLinking(
       // Otherwise, we'll handle it like a regular deep link
       const record = history.get(index)
 
-      if (record?.path === path && record?.state) {
+      // @modified - check both actual path and display path for route masking support
+      const pathMatches = record?.path === path || record?.displayPath === path
+      if (pathMatches && record?.state) {
         if (process.env.ONE_DEBUG_ROUTER) {
           console.info(`[one] 📜 history record found, resetRoot to:`, record.state)
         }
@@ -461,6 +464,12 @@ export function useLinking(
       const route = findFocusedRoute(state)
       const path = getPathForRoute(route, state)
 
+      // @modified - extract mask from linkOptions for route masking
+      const maskHref = (state as any).linkOptions?.mask?.href
+      const displayPath = maskHref
+        ? appendBaseUrl(stripGroupSegmentsFromPath(maskHref) || '/')
+        : undefined
+
       previousStateRef.current = refState
       pendingPopStatePathRef.current = undefined
 
@@ -488,7 +497,7 @@ export function useLinking(
         if (historyDelta > 0) {
           // If history length is increased, we should pushState
           // Note that path might not actually change here, for example, drawer open should pushState
-          history.push({ path, state })
+          history.push({ path, state, displayPath })
         } else if (historyDelta < 0) {
           // If history length is decreased, i.e. entries were removed, we want to go back
 
@@ -512,18 +521,19 @@ export function useLinking(
             }
 
             // Store the updated state as well as fix the path if incorrect
+            // Don't apply mask when going back - use the actual path
             history.replace({ path, state })
           } catch (e) {
             // The navigation was interrupted
           }
         } else {
           // If history length is unchanged, we want to replaceState
-          history.replace({ path, state })
+          history.replace({ path, state, displayPath })
         }
       } else {
         // If no common navigation state was found, assume it's a replace
         // This would happen if the user did a reset/conditionally changed navigators
-        history.replace({ path, state })
+        history.replace({ path, state, displayPath })
       }
     }
 

package/src/index.ts

@@ -71,6 +71,7 @@ export { href } from './href'
 // components
 export { Stack } from './layouts/Stack'
 export { Tabs } from './layouts/Tabs'
+export { Protected, type ProtectedProps } from './views/Protected'
 // utilities
 export { withLayoutContext } from './layouts/withLayoutContext'
 export { Link } from './link/Link'
@@ -86,9 +87,37 @@ export * as routerStore from './router/router'
 export { useNavigation } from './router/useNavigation'
 export { registerPreloadedRoute } from './router/useViteRoutes'
 export type { Endpoint, LoaderProps } from './types'
+// navigation blocking
+export {
+  useBlocker,
+  type Blocker,
+  type BlockerFunction,
+  type BlockerState,
+} from './useBlocker'
+// route param validation
+export {
+  validateParams,
+  zodParamValidator,
+  ParamValidationError,
+  RouteValidationError,
+  type ParamValidator,
+  type InferParamInput,
+  type InferParamOutput,
+  type ValidateRouteProps,
+  type ValidationResult,
+  type RouteValidationFn,
+} from './validateParams'
+// validation state hook
+export { useValidationState, type ValidationState } from './router/router'
 // React Navigation
 export { useFocusEffect } from './useFocusEffect'
-export { refetchLoader, useLoader, useLoaderState } from './useLoader'
+export {
+  getLoaderTimingHistory,
+  refetchLoader,
+  useLoader,
+  useLoaderState,
+  type LoaderTimingEntry,
+} from './useLoader'
 export {
   type ServerHeadInsertionCallback,
   useServerHeadInsertion,
@@ -97,8 +126,12 @@ export { isResponse } from './utils/isResponse'
 export { redirect } from './utils/redirect'
 export { watchFile } from './utils/watchFile'
 export { ErrorBoundary } from './views/ErrorBoundary'
+export type { ErrorBoundaryProps, ErrorRouteInfo } from './views/Try'
 export { LoadProgressBar } from './views/LoadProgressBar'
 export { Navigator, Slot } from './views/Navigator'
 export { ScrollBehavior } from './views/ScrollBehavior'
+export { SourceInspector, type SourceInspectorProps } from './views/SourceInspector'
+// scroll position groups
+export { useScrollGroup } from './useScrollGroup'
 // server
 export { getServerData, setResponseHeaders, setServerData } from './vite/one-server-only'

package/src/interfaces/router.ts

@@ -65,6 +65,41 @@ export namespace OneRouter {
 
   export type LinkToOptions = {
     scroll?: boolean
+    /**
+     * Display a different URL in the browser than the actual route.
+     * Useful for modals and overlays that should show a clean URL.
+     *
+     * @example
+     * ```tsx
+     * // Navigate to /photos/5/modal but show /photos/5 in browser
+     * router.navigate('/photos/5/modal', {
+     *   mask: { href: '/photos/5' }
+     * })
+     * ```
+     */
+    mask?: {
+      /** The URL to display in the browser address bar */
+      href: Href
+      /**
+       * If true, unmask on page reload (show the masked URL in browser).
+       * If false (default), keep masking (navigate to actual route on reload).
+       */
+      unmaskOnReload?: boolean
+    }
+    /**
+     * Specify a scroll group for this navigation.
+     * Routes within the same scroll group will preserve scroll position
+     * when navigating between them.
+     *
+     * @example
+     * ```tsx
+     * // Use scroll group to preserve scroll when switching tabs
+     * router.navigate('/dashboard/settings', {
+     *   scrollGroup: '/dashboard'
+     * })
+     * ```
+     */
+    scrollGroup?: string
   }
 
   type SearchOrHash = `?${string}` | `#${string}`
@@ -359,6 +394,19 @@ export namespace OneRouter {
     /** On web, this sets the HTML `class` directly. On native, this can be used with CSS interop tools like Nativewind. */
     className?: string
 
+    /**
+     * Display a different URL in the browser than the actual route.
+     * Useful for modals and overlays that should show a clean URL.
+     *
+     * @example
+     * ```tsx
+     * <Link href="/photos/5/modal" mask="/photos/5">
+     *   View Photo
+     * </Link>
+     * ```
+     */
+    mask?: Href<T>
+
     onPress?: (
       e: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent
     ) => void

package/src/layouts/withLayoutContext.tsx

@@ -1,9 +1,11 @@
 import type { EventMapBase, NavigationState } from '@react-navigation/native'
 import React from 'react'
 import { useContextKey } from '../router/Route'
+import { registerProtectedRoutes, unregisterProtectedRoutes } from '../router/router'
 import { type ScreenProps, useSortedScreens } from '../router/useScreens'
 import type { PickPartial } from '../types'
 import { withStaticProperties } from '../utils/withStaticProperties'
+import { isProtectedElement } from '../views/Protected'
 import { Screen } from '../views/Screen'
 
 export function useFilterScreenChildren(
@@ -19,9 +21,16 @@ export function useFilterScreenChildren(
 ) {
   return React.useMemo(() => {
     const customChildren: any[] = []
+    const screens: any[] = []
+    const protectedScreens = new Set<string>()
 
-    const screens = React.Children.map(children, (child) => {
-      if (React.isValidElement(child) && child && child.type === Screen) {
+    /**
+     * Recursively process children, handling Protected elements.
+     * When exclude is true, all Screen children are added to protectedScreens instead of screens.
+     */
+    function flattenChild(child: React.ReactNode, exclude = false) {
+      // Handle Screen elements
+      if (React.isValidElement(child) && child.type === Screen) {
         if (
           typeof child.props === 'object' &&
           child.props &&
@@ -44,24 +53,42 @@ export function useFilterScreenChildren(
             )
           }
         }
-        return child.props as ScreenProps
+
+        const screenProps = child.props as ScreenProps
+        if (exclude && screenProps.name) {
+          protectedScreens.add(screenProps.name)
+        } else {
+          screens.push(screenProps)
+        }
+        return
+      }
+
+      // Handle Protected elements - recursively process children with guard logic
+      if (isProtectedElement(child)) {
+        // Key logic: exclude if parent excluded OR guard is false
+        const excludeChildren = exclude || !child.props.guard
+        React.Children.forEach(child.props.children, (nested) => {
+          flattenChild(nested, excludeChildren)
+        })
+        return
       }
 
+      // Handle other children (custom components in custom Navigator)
       if (isCustomNavigator) {
         customChildren.push(child)
-      } else {
+      } else if (child != null) {
         console.warn(
           `Layout children must be of type Screen, all other children are ignored. To use custom children, create a custom <Layout />. Update Layout Route at: "app${contextKey}/_layout"`
         )
       }
+    }
 
-      return null
-    })?.filter(Boolean)
+    React.Children.forEach(children, (child) => flattenChild(child))
 
     // Add an assertion for development
     if (process.env.NODE_ENV !== 'production') {
       // Assert if names are not unique
-      const names = screens?.map((screen) => screen.name)
+      const names = screens.map((screen) => screen.name)
       if (names && new Set(names).size !== names.length) {
         throw new Error('Screen names must be unique: ' + names)
       }
@@ -70,6 +97,7 @@ export function useFilterScreenChildren(
     return {
       screens,
       children: customChildren,
+      protectedScreens,
     }
   }, [children, contextKey, isCustomNavigator])
 }
@@ -92,13 +120,25 @@ export function withLayoutContext<
       (propsIn, ref) => {
         const { children, ...props } = propsIn as React.ComponentProps<T>
         const contextKey = useContextKey()
-        const { screens } = useFilterScreenChildren(children, {
+        const { screens, protectedScreens } = useFilterScreenChildren(children, {
           contextKey,
         })
 
+        // Register protected routes globally so linkTo can block navigation to them
+        // Register immediately (not just in effect) to catch navigation attempts during first render
+        registerProtectedRoutes(contextKey, protectedScreens)
+
+        React.useEffect(() => {
+          registerProtectedRoutes(contextKey, protectedScreens)
+          return () => {
+            unregisterProtectedRoutes(contextKey)
+          }
+        }, [contextKey, protectedScreens])
+
         const processed = processor ? processor(screens ?? ([] as any)) : screens
         const sorted = useSortedScreens((processed ?? []) as any, {
           onlyMatching: true,
+          protectedScreens,
         })
 
         // Prevent throwing an error when there are no screens.

package/src/link/Link.tsx

@@ -25,6 +25,7 @@ export const Link = React.forwardRef(function Link(
     replace,
     push,
     id,
+    mask,
     // TODO: This does not prevent default on the anchor tag.
     asChild,
     rel,
@@ -47,7 +48,11 @@ export const Link = React.forwardRef(function Link(
     return resolveHref(href)
   }, [href])
 
-  const props = useLinkTo({ href: resolvedHref, replace })
+  const resolvedMask = React.useMemo(() => {
+    return mask ? resolveHref(mask) : undefined
+  }, [mask])
+
+  const props = useLinkTo({ href: resolvedHref, replace, mask: resolvedMask })
 
   const onPress = (
     e: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent
@@ -67,7 +72,7 @@ export const Link = React.forwardRef(function Link(
       {...props}
       {...hrefAttrs}
       {...rest}
-      nativeID={id}
+      {...(process.env.TAMAGUI_TARGET === 'web' ? { id } : { nativeID: id })}
       style={asChild ? null : style}
       {...Platform.select({
         web: {

package/src/link/useLinkTo.tsx

@@ -29,7 +29,7 @@ function eventShouldPreventDefault(
   return false
 }
 
-export function useLinkTo(props: { href: string; replace?: boolean }) {
+export function useLinkTo(props: { href: string; replace?: boolean; mask?: string }) {
   const { linkTo } = useOneRouter()
 
   const onPress = (
@@ -46,13 +46,17 @@ export function useLinkTo(props: { href: string; replace?: boolean }) {
     }
 
     if (shouldHandle) {
-      linkTo(props.href, event)
+      const options = props.mask ? { mask: { href: props.mask } } : undefined
+      linkTo(props.href, event, options)
     }
   }
 
+  // For the displayed href, use the mask if provided (shows clean URL in status bar on hover)
+  const displayHref = props.mask || props.href
+
   return {
     // Ensure there's always a value for href. Manually append the baseUrl to the href prop that shows in the static HTML.
-    href: appendBaseUrl(stripGroupSegmentsFromPath(props.href) || '/'),
+    href: appendBaseUrl(stripGroupSegmentsFromPath(displayHref) || '/'),
     role: 'link' as const,
     onPress,
   }

package/src/router/Route.tsx

@@ -1,6 +1,8 @@
 import React, { createContext, type ReactNode, useContext } from 'react'
 import type { ErrorBoundaryProps } from '../views/Try'
+import type { LoaderProps } from '../types'
 import type { One } from '../vite/types'
+import type { ParamValidator, RouteValidationFn } from '../validateParams'
 import { getContextKey } from './matchers'
 import { RouteInfoContextProvider } from './RouteInfoContext'
 
@@ -18,9 +20,36 @@ export type LoadedRoute = {
   generateStaticParams?: (props: {
     params?: Record<string, string | string[]>
   }) => Record<string, string | string[]>[]
-  loader?: (props: {
-    params?: Record<string, string | string[]>
-  }) => Record<string, string | string[]>[]
+  loader?: (props: LoaderProps) => Record<string, string | string[]>[]
+  /**
+   * Validate route params before navigation.
+   * Use with Zod, Valibot, or a custom function.
+   *
+   * @example
+   * ```ts
+   * import { z } from 'zod'
+   * export const validateParams = z.object({
+   *   id: z.string().uuid()
+   * })
+   * ```
+   */
+  validateParams?: ParamValidator
+  /**
+   * Async route validation function.
+   * Runs before navigation to validate the route is accessible.
+   *
+   * @example
+   * ```ts
+   * export async function validateRoute({ params }) {
+   *   const exists = await checkResourceExists(params.id)
+   *   if (!exists) {
+   *     return { valid: false, error: 'Resource not found' }
+   *   }
+   *   return { valid: true }
+   * }
+   * ```
+   */
+  validateRoute?: RouteValidationFn
 }
 
 export type RouteNode = {

package/src/router/findRouteNode.ts

@@ -0,0 +1,127 @@
+import type { RouteNode } from './Route'
+
+/**
+ * Find a RouteNode from the route tree based on the navigation state.
+ * Walks through the state's routes recursively to find the deepest matching route.
+ */
+export function findRouteNodeFromState(
+  state: { routes: Array<{ name: string; state?: any }> } | undefined,
+  rootNode: RouteNode | null
+): RouteNode | null {
+  if (!state || !rootNode) {
+    return null
+  }
+
+  // Get the current route from state (the active one based on index)
+  const currentRoute = state.routes[state.routes.length - 1]
+  if (!currentRoute) {
+    return null
+  }
+
+  // Find the matching child node
+  const matchingNode = findNodeByRouteName(rootNode, currentRoute.name)
+  if (!matchingNode) {
+    return null
+  }
+
+  // If there's a nested state, continue recursively
+  if (currentRoute.state && currentRoute.state.routes) {
+    const nestedResult = findRouteNodeFromState(currentRoute.state, matchingNode)
+    if (nestedResult) {
+      return nestedResult
+    }
+  }
+
+  return matchingNode
+}
+
+/**
+ * Find a node by its route name in the tree.
+ * Searches children recursively.
+ */
+function findNodeByRouteName(node: RouteNode, routeName: string): RouteNode | null {
+  // Check if this node matches
+  if (node.route === routeName) {
+    return node
+  }
+
+  // Search children
+  for (const child of node.children) {
+    const found = findNodeByRouteName(child, routeName)
+    if (found) {
+      return found
+    }
+  }
+
+  return null
+}
+
+/**
+ * Extract params from navigation state.
+ * Collects params from all routes in the state hierarchy.
+ */
+export function extractParamsFromState(
+  state:
+    | { routes: Array<{ name: string; params?: Record<string, any>; state?: any }> }
+    | undefined
+): Record<string, string | string[]> {
+  if (!state) {
+    return {}
+  }
+
+  const params: Record<string, string | string[]> = {}
+
+  // Collect params from all routes in the state
+  for (const route of state.routes) {
+    if (route.params) {
+      Object.assign(params, route.params)
+    }
+    // Recurse into nested state
+    if (route.state) {
+      Object.assign(params, extractParamsFromState(route.state))
+    }
+  }
+
+  return params
+}
+
+/**
+ * Extract search params from href string.
+ */
+export function extractSearchFromHref(href: string): Record<string, string | string[]> {
+  const searchIndex = href.indexOf('?')
+  if (searchIndex === -1) {
+    return {}
+  }
+
+  const searchString = href.slice(searchIndex + 1)
+  const params: Record<string, string | string[]> = {}
+  const searchParams = new URLSearchParams(searchString)
+
+  searchParams.forEach((value, key) => {
+    const existing = params[key]
+    if (existing === undefined) {
+      params[key] = value
+    } else if (Array.isArray(existing)) {
+      existing.push(value)
+    } else {
+      params[key] = [existing, value]
+    }
+  })
+
+  return params
+}
+
+/**
+ * Extract pathname from href string.
+ */
+export function extractPathnameFromHref(href: string): string {
+  const searchIndex = href.indexOf('?')
+  const hashIndex = href.indexOf('#')
+
+  let endIndex = href.length
+  if (searchIndex !== -1) endIndex = Math.min(endIndex, searchIndex)
+  if (hashIndex !== -1) endIndex = Math.min(endIndex, hashIndex)
+
+  return href.slice(0, endIndex)
+}