@depup/tanstack__react-router 1.166.4-depup.0

package/src/useNavigate.tsx

@@ -0,0 +1,78 @@
+import * as React from 'react'
+import { useLayoutEffect } from './utils'
+import { useRouter } from './useRouter'
+import type {
+  AnyRouter,
+  FromPathOption,
+  NavigateOptions,
+  RegisteredRouter,
+  UseNavigateResult,
+} from '@tanstack/router-core'
+
+/**
+ * Imperative navigation hook.
+ *
+ * Returns a stable `navigate(options)` function to change the current location
+ * programmatically. Prefer the `Link` component for user-initiated navigation,
+ * and use this hook from effects, callbacks, or handlers where imperative
+ * navigation is required.
+ *
+ * Options:
+ * - `from`: Optional route base used to resolve relative `to` paths.
+ *
+ * @returns A function that accepts `NavigateOptions`.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useNavigateHook
+ */
+export function useNavigate<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TDefaultFrom extends string = string,
+>(_defaultOpts?: {
+  from?: FromPathOption<TRouter, TDefaultFrom>
+}): UseNavigateResult<TDefaultFrom> {
+  const router = useRouter()
+
+  return React.useCallback(
+    (options: NavigateOptions) => {
+      return router.navigate({
+        ...options,
+        from: options.from ?? _defaultOpts?.from,
+      })
+    },
+    [_defaultOpts?.from, router],
+  ) as UseNavigateResult<TDefaultFrom>
+}
+
+/**
+ * Component that triggers a navigation when rendered. Navigation executes
+ * in an effect after mount/update.
+ *
+ * Props are the same as `NavigateOptions` used by `navigate()`.
+ *
+ * @returns null
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/navigateComponent
+ */
+export function Navigate<
+  TRouter extends AnyRouter = RegisteredRouter,
+  const TFrom extends string = string,
+  const TTo extends string | undefined = undefined,
+  const TMaskFrom extends string = TFrom,
+  const TMaskTo extends string = '',
+>(props: NavigateOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>): null {
+  const router = useRouter()
+  const navigate = useNavigate()
+
+  const previousPropsRef = React.useRef<NavigateOptions<
+    TRouter,
+    TFrom,
+    TTo,
+    TMaskFrom,
+    TMaskTo
+  > | null>(null)
+  useLayoutEffect(() => {
+    if (previousPropsRef.current !== props) {
+      navigate(props)
+      previousPropsRef.current = props
+    }
+  }, [router, props, navigate])
+  return null
+}

package/src/useParams.tsx

@@ -0,0 +1,107 @@
+import { useMatch } from './useMatch'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
+import type {
+  AnyRouter,
+  RegisteredRouter,
+  ResolveUseParams,
+  StrictOrFrom,
+  ThrowConstraint,
+  ThrowOrOptional,
+  UseParamsResult,
+} from '@tanstack/router-core'
+
+export interface UseParamsBaseOptions<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TThrow extends boolean,
+  TSelected,
+  TStructuralSharing,
+> {
+  select?: (
+    params: ResolveUseParams<TRouter, TFrom, TStrict>,
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
+  shouldThrow?: TThrow
+}
+
+export type UseParamsOptions<
+  TRouter extends AnyRouter,
+  TFrom extends string | undefined,
+  TStrict extends boolean,
+  TThrow extends boolean,
+  TSelected,
+  TStructuralSharing,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+  UseParamsBaseOptions<
+    TRouter,
+    TFrom,
+    TStrict,
+    TThrow,
+    TSelected,
+    TStructuralSharing
+  > &
+  StructuralSharingOption<TRouter, TSelected, TStructuralSharing>
+
+export type UseParamsRoute<out TFrom> = <
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseParamsBaseOptions<
+    TRouter,
+    TFrom,
+    /* TStrict */ true,
+    /* TThrow */ true,
+    TSelected,
+    TStructuralSharing
+  > &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+) => UseParamsResult<TRouter, TFrom, true, TSelected>
+
+/**
+ * Access the current route's path parameters with type-safety.
+ *
+ * Options:
+ * - `from`/`strict`: Specify the matched route and whether to enforce strict typing
+ * - `select`: Project the params object to a derived value for memoized renders
+ * - `structuralSharing`: Enable structural sharing for stable references
+ * - `shouldThrow`: Throw if the route is not found in strict contexts
+ *
+ * @returns The params object (or selected value) for the matched route.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useParamsHook
+ */
+export function useParams<
+  TRouter extends AnyRouter = RegisteredRouter,
+  const TFrom extends string | undefined = undefined,
+  TStrict extends boolean = true,
+  TThrow extends boolean = true,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts: UseParamsOptions<
+    TRouter,
+    TFrom,
+    TStrict,
+    ThrowConstraint<TStrict, TThrow>,
+    TSelected,
+    TStructuralSharing
+  >,
+): ThrowOrOptional<
+  UseParamsResult<TRouter, TFrom, TStrict, TSelected>,
+  TThrow
+> {
+  return useMatch({
+    from: opts.from!,
+    shouldThrow: opts.shouldThrow,
+    structuralSharing: opts.structuralSharing,
+    strict: opts.strict,
+    select: (match) => {
+      const params = opts.strict === false ? match.params : match._strictParams
+
+      return opts.select ? opts.select(params) : params
+    },
+  }) as any
+}

package/src/useRouteContext.ts

@@ -0,0 +1,30 @@
+import { useMatch } from './useMatch'
+import type {
+  AnyRouter,
+  RegisteredRouter,
+  UseRouteContextBaseOptions,
+  UseRouteContextOptions,
+  UseRouteContextResult,
+} from '@tanstack/router-core'
+
+export type UseRouteContextRoute<out TFrom> = <
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+>(
+  opts?: UseRouteContextBaseOptions<TRouter, TFrom, true, TSelected>,
+) => UseRouteContextResult<TRouter, TFrom, true, TSelected>
+
+export function useRouteContext<
+  TRouter extends AnyRouter = RegisteredRouter,
+  const TFrom extends string | undefined = undefined,
+  TStrict extends boolean = true,
+  TSelected = unknown,
+>(
+  opts: UseRouteContextOptions<TRouter, TFrom, TStrict, TSelected>,
+): UseRouteContextResult<TRouter, TFrom, TStrict, TSelected> {
+  return useMatch({
+    ...(opts as any),
+    select: (match) =>
+      opts.select ? opts.select(match.context) : match.context,
+  }) as UseRouteContextResult<TRouter, TFrom, TStrict, TSelected>
+}

package/src/useRouter.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react'
+import warning from 'tiny-warning'
+import { routerContext } from './routerContext'
+import type { AnyRouter, RegisteredRouter } from '@tanstack/router-core'
+
+/**
+ * Access the current TanStack Router instance from React context.
+ * Must be used within a `RouterProvider`.
+ *
+ * Options:
+ * - `warn`: Log a warning if no router context is found (default: true).
+ *
+ * @returns The registered router instance.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useRouterHook
+ */
+export function useRouter<TRouter extends AnyRouter = RegisteredRouter>(opts?: {
+  warn?: boolean
+}): TRouter {
+  const value = React.useContext(routerContext)
+  warning(
+    !((opts?.warn ?? true) && !value),
+    'useRouter must be used inside a <RouterProvider> component!',
+  )
+  return value as any
+}

package/src/useRouterState.tsx

@@ -0,0 +1,86 @@
+import { useStore } from '@tanstack/react-store'
+import { useRef } from 'react'
+import { replaceEqualDeep } from '@tanstack/router-core'
+import { isServer } from '@tanstack/router-core/isServer'
+import { useRouter } from './useRouter'
+import type {
+  AnyRouter,
+  RegisteredRouter,
+  RouterState,
+} from '@tanstack/router-core'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
+
+export type UseRouterStateOptions<
+  TRouter extends AnyRouter,
+  TSelected,
+  TStructuralSharing,
+> = {
+  router?: TRouter
+  select?: (
+    state: RouterState<TRouter['routeTree']>,
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
+} & StructuralSharingOption<TRouter, TSelected, TStructuralSharing>
+
+export type UseRouterStateResult<
+  TRouter extends AnyRouter,
+  TSelected,
+> = unknown extends TSelected ? RouterState<TRouter['routeTree']> : TSelected
+
+/**
+ * Subscribe to the router's state store with optional selection and
+ * structural sharing for render optimization.
+ *
+ * Options:
+ * - `select`: Project the full router state to a derived slice
+ * - `structuralSharing`: Replace-equal semantics for stable references
+ * - `router`: Read state from a specific router instance instead of context
+ *
+ * @returns The selected router state (or the full state by default).
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useRouterStateHook
+ */
+export function useRouterState<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseRouterStateOptions<TRouter, TSelected, TStructuralSharing>,
+): UseRouterStateResult<TRouter, TSelected> {
+  const contextRouter = useRouter<TRouter>({
+    warn: opts?.router === undefined,
+  })
+  const router = opts?.router || contextRouter
+
+  // During SSR we render exactly once and do not need reactivity.
+  // Avoid subscribing to the store (and any structural sharing work) on the server.
+  const _isServer = isServer ?? router.isServer
+  if (_isServer) {
+    const state = router.state as RouterState<TRouter['routeTree']>
+    return (opts?.select ? opts.select(state) : state) as UseRouterStateResult<
+      TRouter,
+      TSelected
+    >
+  }
+
+  const previousResult =
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useRef<ValidateSelected<TRouter, TSelected, TStructuralSharing>>(undefined)
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  return useStore(router.__store, (state) => {
+    if (opts?.select) {
+      if (opts.structuralSharing ?? router.options.defaultStructuralSharing) {
+        const newSlice = replaceEqualDeep(
+          previousResult.current,
+          opts.select(state),
+        )
+        previousResult.current = newSlice
+        return newSlice
+      }
+      return opts.select(state)
+    }
+    return state
+  }) as UseRouterStateResult<TRouter, TSelected>
+}

package/src/useSearch.tsx

@@ -0,0 +1,105 @@
+import { useMatch } from './useMatch'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
+import type {
+  AnyRouter,
+  RegisteredRouter,
+  ResolveUseSearch,
+  StrictOrFrom,
+  ThrowConstraint,
+  ThrowOrOptional,
+  UseSearchResult,
+} from '@tanstack/router-core'
+
+export interface UseSearchBaseOptions<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TThrow extends boolean,
+  TSelected,
+  TStructuralSharing,
+> {
+  select?: (
+    state: ResolveUseSearch<TRouter, TFrom, TStrict>,
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
+  shouldThrow?: TThrow
+}
+
+export type UseSearchOptions<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TThrow extends boolean,
+  TSelected,
+  TStructuralSharing,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+  UseSearchBaseOptions<
+    TRouter,
+    TFrom,
+    TStrict,
+    TThrow,
+    TSelected,
+    TStructuralSharing
+  > &
+  StructuralSharingOption<TRouter, TSelected, TStructuralSharing>
+
+export type UseSearchRoute<out TFrom> = <
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseSearchBaseOptions<
+    TRouter,
+    TFrom,
+    /* TStrict */ true,
+    /* TThrow */ true,
+    TSelected,
+    TStructuralSharing
+  > &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+) => UseSearchResult<TRouter, TFrom, true, TSelected>
+
+/**
+ * Read and select the current route's search parameters with type-safety.
+ *
+ * Options:
+ * - `from`/`strict`: Control which route's search is read and how strictly it's typed
+ * - `select`: Map the search object to a derived value for render optimization
+ * - `structuralSharing`: Enable structural sharing for stable references
+ * - `shouldThrow`: Throw when the route is not found (strict contexts)
+ *
+ * @returns The search object (or selected value) for the matched route.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useSearchHook
+ */
+export function useSearch<
+  TRouter extends AnyRouter = RegisteredRouter,
+  const TFrom extends string | undefined = undefined,
+  TStrict extends boolean = true,
+  TThrow extends boolean = true,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts: UseSearchOptions<
+    TRouter,
+    TFrom,
+    TStrict,
+    ThrowConstraint<TStrict, TThrow>,
+    TSelected,
+    TStructuralSharing
+  >,
+): ThrowOrOptional<
+  UseSearchResult<TRouter, TFrom, TStrict, TSelected>,
+  TThrow
+> {
+  return useMatch({
+    from: opts.from!,
+    strict: opts.strict,
+    shouldThrow: opts.shouldThrow,
+    structuralSharing: opts.structuralSharing,
+    select: (match: any) => {
+      return opts.select ? opts.select(match.search) : match.search
+    },
+  }) as any
+}

package/src/utils.ts

@@ -0,0 +1,125 @@
+import * as React from 'react'
+
+// Safe version of React.use() that will not cause compilation errors against
+// React 18 with Webpack, which statically analyzes imports and fails when it
+// sees React.use referenced (since 'use' is not exported from React 18).
+// This uses a dynamic string lookup to avoid the static analysis.
+const REACT_USE = 'use'
+
+/**
+ * React.use if available (React 19+), undefined otherwise.
+ * Use dynamic lookup to avoid Webpack compilation errors with React 18.
+ */
+export const reactUse:
+  | (<T>(usable: Promise<T> | React.Context<T>) => T)
+  | undefined = (React as any)[REACT_USE]
+
+export function useStableCallback<T extends (...args: Array<any>) => any>(
+  fn: T,
+): T {
+  const fnRef = React.useRef(fn)
+  fnRef.current = fn
+
+  const ref = React.useRef((...args: Array<any>) => fnRef.current(...args))
+  return ref.current as T
+}
+
+export const useLayoutEffect =
+  typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect
+
+/**
+ * Taken from https://www.developerway.com/posts/implementing-advanced-use-previous-hook#part3
+ */
+export function usePrevious<T>(value: T): T | null {
+  // initialise the ref with previous and current values
+  const ref = React.useRef<{ value: T; prev: T | null }>({
+    value: value,
+    prev: null,
+  })
+
+  const current = ref.current.value
+
+  // if the value passed into hook doesn't match what we store as "current"
+  // move the "current" to the "previous"
+  // and store the passed value as "current"
+  if (value !== current) {
+    ref.current = {
+      value: value,
+      prev: current,
+    }
+  }
+
+  // return the previous value only
+  return ref.current.prev
+}
+
+/**
+ * React hook to wrap `IntersectionObserver`.
+ *
+ * This hook will create an `IntersectionObserver` and observe the ref passed to it.
+ *
+ * When the intersection changes, the callback will be called with the `IntersectionObserverEntry`.
+ *
+ * @param ref - The ref to observe
+ * @param intersectionObserverOptions - The options to pass to the IntersectionObserver
+ * @param options - The options to pass to the hook
+ * @param callback - The callback to call when the intersection changes
+ * @returns The IntersectionObserver instance
+ * @example
+ * ```tsx
+ * const MyComponent = () => {
+ * const ref = React.useRef<HTMLDivElement>(null)
+ * useIntersectionObserver(
+ *  ref,
+ *  (entry) => { doSomething(entry) },
+ *  { rootMargin: '10px' },
+ *  { disabled: false }
+ * )
+ * return <div ref={ref} />
+ * ```
+ */
+export function useIntersectionObserver<T extends Element>(
+  ref: React.RefObject<T | null>,
+  callback: (entry: IntersectionObserverEntry | undefined) => void,
+  intersectionObserverOptions: IntersectionObserverInit = {},
+  options: { disabled?: boolean } = {},
+) {
+  React.useEffect(() => {
+    if (
+      !ref.current ||
+      options.disabled ||
+      typeof IntersectionObserver !== 'function'
+    ) {
+      return
+    }
+
+    const observer = new IntersectionObserver(([entry]) => {
+      callback(entry)
+    }, intersectionObserverOptions)
+
+    observer.observe(ref.current)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [callback, intersectionObserverOptions, options.disabled, ref])
+}
+
+/**
+ * React hook to take a `React.ForwardedRef` and returns a `ref` that can be used on a DOM element.
+ *
+ * @param ref - The forwarded ref
+ * @returns The inner ref returned by `useRef`
+ * @example
+ * ```tsx
+ * const MyComponent = React.forwardRef((props, ref) => {
+ *  const innerRef = useForwardedRef(ref)
+ *  return <div ref={innerRef} />
+ * })
+ * ```
+ */
+export function useForwardedRef<T>(ref?: React.ForwardedRef<T>) {
+  const innerRef = React.useRef<T>(null)
+  React.useImperativeHandle(ref, () => innerRef.current!, [])
+  return innerRef
+}