one 1.2.57 → 1.2.59

package/src/useBlocker.ts

@@ -0,0 +1,340 @@
+import * as React from 'react'
+import { Platform } from 'react-native'
+
+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
+    }
+
+/**
+ * Stored pending navigation that was blocked.
+ * We need to restore it when the user confirms.
+ */
+type PendingNavigation = {
+  previousLocation: string
+  nextLocation: string
+  historyAction: 'push' | 'pop' | 'replace'
+}
+
+// Global state for blocking
+let currentLocation =
+  typeof window !== 'undefined' ? window.location.pathname + window.location.search : ''
+let isBlocking = false
+let isProceeding = false
+let pendingNavigation: PendingNavigation | null = null
+
+// Active blocker callbacks
+const blockerCallbacks = new Map<
+  symbol,
+  {
+    shouldBlock: () => boolean
+    onBlock: (pending: PendingNavigation) => void
+    onProceed: () => void
+    onReset: () => void
+  }
+>()
+
+// Track if global listeners are set up
+let listenersSetup = false
+
+function setupListeners() {
+  if (listenersSetup || typeof window === 'undefined') return
+  listenersSetup = true
+
+  // Track current location on page load
+  currentLocation = window.location.pathname + window.location.search
+
+  // Listen for popstate (browser back/forward)
+  window.addEventListener('popstate', () => {
+    if (isProceeding) return
+
+    const nextLocation = window.location.pathname + window.location.search
+
+    // Check if any blocker wants to block
+    for (const [, callbacks] of blockerCallbacks) {
+      if (callbacks.shouldBlock()) {
+        // Block the navigation
+        isBlocking = true
+        pendingNavigation = {
+          previousLocation: currentLocation,
+          nextLocation,
+          historyAction: 'pop',
+        }
+
+        // Restore the previous URL immediately using history.forward() or history.back()
+        // We pushed a state when we got here, so we need to go back
+        window.history.go(1) // Go forward to restore
+
+        // Notify the blocker
+        callbacks.onBlock(pendingNavigation)
+        return
+      }
+    }
+
+    // No blocking, update current location
+    currentLocation = nextLocation
+  })
+
+  // Intercept pushState and replaceState
+  const originalPushState = window.history.pushState.bind(window.history)
+  const originalReplaceState = window.history.replaceState.bind(window.history)
+
+  window.history.pushState = function (state, title, url) {
+    if (isProceeding || !url) {
+      return originalPushState(state, title, url)
+    }
+
+    const nextLocation = typeof url === 'string' ? url : url.toString()
+
+    for (const [, callbacks] of blockerCallbacks) {
+      if (callbacks.shouldBlock()) {
+        isBlocking = true
+        pendingNavigation = {
+          previousLocation: currentLocation,
+          nextLocation,
+          historyAction: 'push',
+        }
+        callbacks.onBlock(pendingNavigation)
+        return // Don't call original
+      }
+    }
+
+    currentLocation = nextLocation
+    return originalPushState(state, title, url)
+  }
+
+  window.history.replaceState = function (state, title, url) {
+    if (isProceeding || !url) {
+      return originalReplaceState(state, title, url)
+    }
+
+    const nextLocation = typeof url === 'string' ? url : url.toString()
+
+    for (const [, callbacks] of blockerCallbacks) {
+      if (callbacks.shouldBlock()) {
+        isBlocking = true
+        pendingNavigation = {
+          previousLocation: currentLocation,
+          nextLocation,
+          historyAction: 'replace',
+        }
+        callbacks.onBlock(pendingNavigation)
+        return // Don't call original
+      }
+    }
+
+    currentLocation = nextLocation
+    return originalReplaceState(state, title, url)
+  }
+
+  // Handle beforeunload (page close/refresh)
+  window.addEventListener('beforeunload', (event) => {
+    for (const [, callbacks] of blockerCallbacks) {
+      if (callbacks.shouldBlock()) {
+        event.preventDefault()
+        event.returnValue = ''
+        return
+      }
+    }
+  })
+}
+
+/**
+ * Block navigation when a condition is met.
+ *
+ * This is useful for preventing users from accidentally leaving a page with unsaved changes.
+ * Works with both browser navigation (back/forward, URL changes) and programmatic navigation.
+ *
+ * @param shouldBlock - Either a boolean or a function that returns whether to block.
+ *   When using a function, you receive the current and next locations and can make dynamic decisions.
+ *
+ * @example
+ * ```tsx
+ * function EditForm() {
+ *   const [isDirty, setIsDirty] = useState(false)
+ *   const blocker = useBlocker(isDirty)
+ *
+ *   return (
+ *     <>
+ *       <form onChange={() => setIsDirty(true)}>
+ *         {// form fields}
+ *       </form>
+ *
+ *       {blocker.state === 'blocked' && (
+ *         <Dialog>
+ *           <p>You have unsaved changes. Leave anyway?</p>
+ *           <button onClick={blocker.reset}>Stay</button>
+ *           <button onClick={blocker.proceed}>Leave</button>
+ *         </Dialog>
+ *       )}
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Function-based blocking with location info
+ * const blocker = useBlocker(({ currentLocation, nextLocation }) => {
+ *   // Only block when leaving this specific section
+ *   return currentLocation.startsWith('/edit') && !nextLocation.startsWith('/edit')
+ * })
+ * ```
+ */
+export function useBlocker(shouldBlock: BlockerFunction | boolean): Blocker {
+  const [state, setState] = React.useState<BlockerState>('unblocked')
+  const [blockedLocation, setBlockedLocation] = React.useState<string | null>(null)
+  const idRef = React.useRef<symbol | null>(null)
+
+  const shouldBlockRef = React.useRef(shouldBlock)
+  shouldBlockRef.current = shouldBlock
+
+  React.useEffect(() => {
+    // Only run on web
+    if (Platform.OS !== 'web' || typeof window === 'undefined') return
+
+    setupListeners()
+
+    const id = Symbol('blocker')
+    idRef.current = id
+
+    blockerCallbacks.set(id, {
+      shouldBlock: () => {
+        const block = shouldBlockRef.current
+        if (typeof block === 'function') {
+          return block({
+            currentLocation,
+            nextLocation: pendingNavigation?.nextLocation || '',
+            historyAction: pendingNavigation?.historyAction || 'push',
+          })
+        }
+        return block
+      },
+      onBlock: (pending) => {
+        setBlockedLocation(pending.nextLocation)
+        setState('blocked')
+      },
+      onProceed: () => {
+        setState('proceeding')
+      },
+      onReset: () => {
+        setState('unblocked')
+        setBlockedLocation(null)
+      },
+    })
+
+    return () => {
+      blockerCallbacks.delete(id)
+    }
+  }, [])
+
+  const reset = React.useCallback(() => {
+    isBlocking = false
+    pendingNavigation = null
+    setBlockedLocation(null)
+    setState('unblocked')
+  }, [])
+
+  const proceed = React.useCallback(() => {
+    if (!pendingNavigation) return
+
+    setState('proceeding')
+    isProceeding = true
+
+    const pending = pendingNavigation
+    pendingNavigation = null
+    isBlocking = false
+
+    // Execute the blocked navigation
+    requestAnimationFrame(() => {
+      if (pending.historyAction === 'pop') {
+        // Go back to where the user wanted to go
+        window.history.back()
+      } else if (pending.historyAction === 'push') {
+        window.history.pushState(null, '', pending.nextLocation)
+      } else {
+        window.history.replaceState(null, '', pending.nextLocation)
+      }
+
+      currentLocation = pending.nextLocation
+
+      // Reset state after navigation
+      requestAnimationFrame(() => {
+        isProceeding = false
+        setBlockedLocation(null)
+        setState('unblocked')
+      })
+    })
+  }, [])
+
+  if (state === 'unblocked') {
+    return { state: 'unblocked' }
+  }
+
+  if (state === 'proceeding') {
+    return { state: 'proceeding', location: blockedLocation! }
+  }
+
+  return {
+    state: 'blocked',
+    reset,
+    proceed,
+    location: blockedLocation!,
+  }
+}
+
+/**
+ * Check if any active blocker wants to block navigation.
+ * Called by the router before navigating via Link.
+ * Returns true if navigation was blocked.
+ */
+export function checkBlocker(
+  nextLocation: string,
+  historyAction: 'push' | 'pop' | 'replace' = 'push'
+): boolean {
+  if (Platform.OS !== 'web' || typeof window === 'undefined') {
+    return false
+  }
+
+  if (isProceeding) {
+    return false
+  }
+
+  for (const [, callbacks] of blockerCallbacks) {
+    if (callbacks.shouldBlock()) {
+      isBlocking = true
+      pendingNavigation = {
+        previousLocation: currentLocation,
+        nextLocation,
+        historyAction,
+      }
+      callbacks.onBlock(pendingNavigation)
+      return true
+    }
+  }
+
+  return false
+}

package/src/useFocusEffect.ts

@@ -7,12 +7,25 @@ import { useOptionalNavigation } from './link/useLoadedNavigation'
 type EffectCallback = () => undefined | void | (() => void)
 
 /**
- * Hook to run an effect in a focused screen, similar to `React.useEffect`.
- * This can be used to perform side-effects such as fetching data or subscribing to events.
+ * Run side effects when a screen is focused. The effect runs when the screen
+ * gains focus and cleans up when it loses focus.
  *
- * @param callback Memoized callback containing the effect, should optionally return a cleanup function.
+ * @param effect - Memoized callback containing the effect, optionally returns cleanup function
+ * @param deps - Dependency array, effect re-runs when dependencies change (if focused)
+ * @link https://onestack.dev/docs/api/hooks/useFocusEffect
+ *
+ * @example
+ * ```tsx
+ * useFocusEffect(
+ *   useCallback(() => {
+ *     const subscription = subscribeToUpdates()
+ *     return () => subscription.unsubscribe()
+ *   }, []),
+ *   []
+ * )
+ * ```
  */
-export function useFocusEffect(effect: EffectCallback, args: any[]) {
+export function useFocusEffect(effect: EffectCallback, deps: any[]) {
   const navigation = useOptionalNavigation()
 
   useEffect(() => {
@@ -87,5 +100,5 @@ export function useFocusEffect(effect: EffectCallback, args: any[]) {
       unsubscribeFocus()
       unsubscribeBlur()
     }
-  }, [navigation, ...args])
+  }, [navigation, ...deps])
 }

package/src/useLoader.ts

@@ -1,4 +1,5 @@
-import { useCallback, useDeferredValue, useSyncExternalStore } from 'react'
+import { useCallback, useSyncExternalStore } from 'react'
+import { registerDevtoolsFunction } from './devtools/registry'
 import { useParams, usePathname } from './hooks'
 import { preloadedLoaderData, preloadingLoader } from './router/router'
 import { getLoaderPath } from './utils/cleanUrl'
@@ -15,6 +16,60 @@ type LoaderStateEntry = {
   hasLoadedOnce?: boolean
 }
 
+// Timing data for loader waterfall devtool (dev only)
+export type LoaderTimingEntry = {
+  path: string
+  startTime: number
+  moduleLoadTime?: number
+  executionTime?: number
+  totalTime?: number
+  error?: string
+  source: 'preload' | 'initial' | 'refetch'
+}
+
+// Store timing history for devtools - only populated in development
+const loaderTimingHistory: LoaderTimingEntry[] = []
+const MAX_TIMING_HISTORY = 50
+
+function recordLoaderTiming(entry: LoaderTimingEntry) {
+  if (process.env.NODE_ENV !== 'development') return
+
+  loaderTimingHistory.unshift(entry)
+  if (loaderTimingHistory.length > MAX_TIMING_HISTORY) {
+    loaderTimingHistory.pop()
+  }
+  // Dispatch event for devtools
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(new CustomEvent('one-loader-timing', { detail: entry }))
+
+    // Also dispatch error event if there was an error
+    if (entry.error) {
+      window.dispatchEvent(
+        new CustomEvent('one-error', {
+          detail: {
+            error: {
+              message: entry.error,
+              name: 'LoaderError',
+            },
+            route: {
+              pathname: entry.path,
+            },
+            timestamp: Date.now(),
+            type: 'loader',
+          },
+        })
+      )
+    }
+  }
+}
+
+export function getLoaderTimingHistory(): LoaderTimingEntry[] {
+  return loaderTimingHistory
+}
+
+// Register with devtools registry so router.ts doesn't need to dynamically import us
+registerDevtoolsFunction('getLoaderTimingHistory', getLoaderTimingHistory)
+
 const loaderState: Record<string, LoaderStateEntry> = {}
 const subscribers = new Set<() => void>()
 
@@ -43,7 +98,21 @@ function getLoaderState(path: string, preloadedData?: any): LoaderStateEntry {
   return loaderState[path]
 }
 
+/**
+ * Imperatively refetch loader data for a given path.
+ *
+ * @param pathname - The route path to refetch (e.g., '/users/123')
+ * @returns Promise that resolves when refetch completes
+ * @link https://onestack.dev/docs/api/hooks/useLoaderState#refetchloader
+ *
+ * @example
+ * ```tsx
+ * await refetchLoader('/users/123')
+ * ```
+ */
 export async function refetchLoader(pathname: string): Promise<void> {
+  const startTime = performance.now()
+
   updateState(pathname, {
     state: 'loading',
     error: null,
@@ -53,8 +122,15 @@ export async function refetchLoader(pathname: string): Promise<void> {
     const cacheBust = `${Date.now()}`
     const loaderJSUrl = getLoaderPath(pathname, true, cacheBust)
 
+    const moduleLoadStart = performance.now()
     const module = await dynamicImport(loaderJSUrl)
+    const moduleLoadTime = performance.now() - moduleLoadStart
+
+    const executionStart = performance.now()
     const result = await module.loader()
+    const executionTime = performance.now() - executionStart
+
+    const totalTime = performance.now() - startTime
 
     updateState(pathname, {
       data: result,
@@ -62,19 +138,61 @@ export async function refetchLoader(pathname: string): Promise<void> {
       timestamp: Date.now(),
       hasLoadedOnce: true,
     })
+
+    recordLoaderTiming({
+      path: pathname,
+      startTime,
+      moduleLoadTime,
+      executionTime,
+      totalTime,
+      source: 'refetch',
+    })
   } catch (err) {
+    const totalTime = performance.now() - startTime
+
     updateState(pathname, {
       error: err,
       state: 'idle',
     })
+
+    recordLoaderTiming({
+      path: pathname,
+      startTime,
+      totalTime,
+      error: err instanceof Error ? err.message : String(err),
+      source: 'refetch',
+    })
+
     throw err
   }
 }
 
-if (typeof window !== 'undefined') {
+// Expose refetchLoader globally for HMR in development
+if (process.env.NODE_ENV === 'development' && typeof window !== 'undefined') {
   ;(window as any).__oneRefetchLoader = refetchLoader
 }
 
+/**
+ * Access loader data with full state control including refetch capability.
+ * Use this when you need loading state or refetch; use `useLoader` for just data.
+ *
+ * @param loader - The loader function (optional - omit for just refetch/state)
+ * @returns Object with data, state ('idle' | 'loading'), and refetch function
+ * @link https://onestack.dev/docs/api/hooks/useLoaderState
+ *
+ * @example
+ * ```tsx
+ * const { data, state, refetch } = useLoaderState(loader)
+ *
+ * return (
+ *   <div>
+ *     {state === 'loading' && <Spinner />}
+ *     <button onClick={refetch}>Refresh</button>
+ *     <pre>{JSON.stringify(data)}</pre>
+ *   </div>
+ * )
+ * ```
+ */
 export function useLoaderState<
   Loader extends Function = any,
   Returned = Loader extends (p: any) => any ? ReturnType<Loader> : unknown,
@@ -172,12 +290,15 @@ export function useLoaderState<
     } else {
       // initial load
       const loadData = async () => {
+        const startTime = performance.now()
+
         try {
           if (process.env.TAMAGUI_TARGET === 'native') {
             const loaderJSUrl = getLoaderPath(currentPath, true)
             const nativeLoaderJSUrl = `${loaderJSUrl}?platform=ios`
 
             try {
+              const moduleLoadStart = performance.now()
               const loaderJsCodeResp = await fetch(nativeLoaderJSUrl)
               if (!loaderJsCodeResp.ok) {
                 throw new Error(`Response not ok: ${loaderJsCodeResp.status}`)
@@ -187,41 +308,91 @@ export function useLoaderState<
               const result = eval(
                 `() => { var exports = {}; ${loaderJsCode}; return exports; }`
               )()
+              const moduleLoadTime = performance.now() - moduleLoadStart
 
               if (typeof result.loader !== 'function') {
                 throw new Error("Loader code isn't exporting a `loader` function")
               }
 
+              const executionStart = performance.now()
               const data = await result.loader()
+              const executionTime = performance.now() - executionStart
+              const totalTime = performance.now() - startTime
+
               updateState(currentPath, {
                 data,
                 hasLoadedOnce: true,
                 promise: undefined,
               })
+
+              recordLoaderTiming({
+                path: currentPath,
+                startTime,
+                moduleLoadTime,
+                executionTime,
+                totalTime,
+                source: 'initial',
+              })
               return
             } catch (e) {
+              const totalTime = performance.now() - startTime
               updateState(currentPath, {
                 data: {},
                 promise: undefined,
               })
+              recordLoaderTiming({
+                path: currentPath,
+                startTime,
+                totalTime,
+                error: e instanceof Error ? e.message : String(e),
+                source: 'initial',
+              })
               return
             }
           }
 
           // web platform
           const loaderJSUrl = getLoaderPath(currentPath, true)
+
+          const moduleLoadStart = performance.now()
           const module = await dynamicImport(loaderJSUrl)
+          const moduleLoadTime = performance.now() - moduleLoadStart
+
+          const executionStart = performance.now()
           const result = await module.loader()
+          const executionTime = performance.now() - executionStart
+
+          const totalTime = performance.now() - startTime
+
           updateState(currentPath, {
             data: result,
             hasLoadedOnce: true,
             promise: undefined,
           })
+
+          recordLoaderTiming({
+            path: currentPath,
+            startTime,
+            moduleLoadTime,
+            executionTime,
+            totalTime,
+            source: 'initial',
+          })
         } catch (err) {
+          const totalTime = performance.now() - startTime
+
           updateState(currentPath, {
             error: err,
             promise: undefined,
           })
+
+          recordLoaderTiming({
+            path: currentPath,
+            startTime,
+            totalTime,
+            error: err instanceof Error ? err.message : String(err),
+            source: 'initial',
+          })
         }
       }
 
@@ -259,6 +430,26 @@ export function useLoaderState<
   }
 }
 
+/**
+ * Load route data with SSR/SSG support. Returns the loader's data directly.
+ * For loading state and refetch capability, use `useLoaderState` instead.
+ *
+ * @param loader - The loader function exported from the route file
+ * @returns The awaited return value of your loader function
+ * @link https://onestack.dev/docs/api/hooks/useLoader
+ *
+ * @example
+ * ```tsx
+ * export async function loader({ params }) {
+ *   return { user: await fetchUser(params.id) }
+ * }
+ *
+ * export default function UserPage() {
+ *   const { user } = useLoader(loader)
+ *   return <div>{user.name}</div>
+ * }
+ * ```
+ */
 export function useLoader<
   Loader extends Function,
   Returned = Loader extends (p: any) => any ? ReturnType<Loader> : unknown,

package/src/useScrollGroup.native.ts

@@ -0,0 +1,7 @@
+/**
+ * Native no-op for useScrollGroup.
+ * Scroll position groups are a web-only feature.
+ */
+export function useScrollGroup(_groupPath?: string) {
+  // No-op on native - scroll position is handled differently
+}