@tanstack/react-router 1.45.15 → 1.46.0

package/src/router.ts

@@ -153,218 +153,271 @@ export interface RouterOptions<
 > {
   /**
    * The history object that will be used to manage the browser history.
+   *
    * If not provided, a new createBrowserHistory instance will be created and used.
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#history-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/history-types)
    */
   history?: RouterHistory
   /**
    * A function that will be used to stringify search params when generating links.
-   * Defaults to `defaultStringifySearch`.
+   *
+   * @default defaultStringifySearch
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#stringifysearch-method)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization)
    */
   stringifySearch?: SearchSerializer
   /**
    * A function that will be used to parse search params when parsing the current location.
-   * Defaults to `defaultParseSearch`.
+   *
+   * @default defaultParseSearch
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#parsesearch-method)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization)
    */
   parseSearch?: SearchParser
   /**
-   * Defaults to `false`
    * If `false`, routes will not be preloaded by default in any way.
+   *
    * If `'intent'`, routes will be preloaded by default when the user hovers over a link or a `touchstart` event is detected on a `<Link>`.
+   *
+   * If `'viewport'`, routes will be preloaded by default when they are within the viewport.
+   *
+   * @default false
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreload-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
    */
-  defaultPreload?: false | 'intent'
+  defaultPreload?: false | 'intent' | 'viewport'
   /**
-   * Defaults to 50
    * The delay in milliseconds that a route must be hovered over or touched before it is preloaded.
+   *
+   * @default 50
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreloaddelay-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading#preload-delay)
    */
   defaultPreloadDelay?: number
   /**
-   * Defaults to `Outlet`
    * The default `component` a route should use if no component is provided.
+   *
+   * @default Outlet
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultcomponent-property)
    */
   defaultComponent?: RouteComponent
   /**
-   * Defaults to `ErrorComponent`
    * The default `errorComponent` a route should use if no error component is provided.
+   *
+   * @default ErrorComponent
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaulterrorcomponent-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#handling-errors-with-routeoptionserrorcomponent)
    */
   defaultErrorComponent?: ErrorRouteComponent
   /**
    * The default `pendingComponent` a route should use if no pending component is provided.
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpendingcomponent-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#showing-a-pending-component)
    */
   defaultPendingComponent?: RouteComponent
   /**
-   * Defaults to `1000`
    * The default `pendingMs` a route should use if no pendingMs is provided.
+   *
+   * @default 1000
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpendingms-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#avoiding-pending-component-flash)
    */
   defaultPendingMs?: number
   /**
-   * Defaults to `500`
    * The default `pendingMinMs` a route should use if no pendingMinMs is provided.
+   *
+   * @default 500
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpendingminms-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#avoiding-pending-component-flash)
    */
   defaultPendingMinMs?: number
   /**
-   * Defaults to `0`
-   * The default `staleTime` a route should use if no staleTime is
+   * The default `staleTime` a route should use if no staleTime is provided. This is the time in milliseconds that a route will be considered fresh.
+   *
+   * @default 0
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultstaletime-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#key-options)
    */
   defaultStaleTime?: number
   /**
-   * Defaults to `30_000` ms (30 seconds)
    * The default `preloadStaleTime` a route should use if no preloadStaleTime is provided.
+   *
+   * @default 30_000 `(30 seconds)`
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreloadstaletime-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
    */
   defaultPreloadStaleTime?: number
   /**
    * Defaults to `routerOptions.defaultGcTime`, which defaults to 30 minutes.
+   *
    * The default `defaultPreloadGcTime` a route should use if no preloadGcTime is provided.
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreloadgctime-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
    */
   defaultPreloadGcTime?: number
   /**
    * The default `onCatch` handler for errors caught by the Router ErrorBoundary
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultoncatch-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#handling-errors-with-routeoptionsoncatch)
    */
   defaultOnCatch?: (error: Error, errorInfo: React.ErrorInfo) => void
+  /**
+   * If set to `true`, all navigation actions will wrapped in `document.startViewTransition()`.
+   */
   defaultViewTransition?: boolean
   /**
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/not-found-errors#the-notfoundmode-option)
    */
   notFoundMode?: 'root' | 'fuzzy'
   /**
-   * Defaults to 30 minutes.
    * The default `gcTime` a route should use if no
+   *
+   * @default 1_800_000 `(30 minutes)`
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultgctime-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#key-options)
    */
   defaultGcTime?: number
   /**
-   * Defaults to `false`
    * If `true`, all routes will be matched as case-sensitive.
+   *
+   * @default false
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#casesensitive-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/route-trees#case-sensitivity)
    */
   caseSensitive?: boolean
   /**
-   * Required
+   * __Required*__
+   *
    * The route tree that will be used to configure the router instance.
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#routetree-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/route-trees)
    */
   routeTree?: TRouteTree
   /**
-   * Defaults to `/`
    * The basepath for then entire router. This is useful for mounting a router instance at a subpath.
+   *
+   * @default '/'
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#basepath-property)
    */
   basepath?: string
   /**
-   * Optional or required if the root route was created with [`createRootRouteWithContext()`](https://tanstack.com/router/latest/docs/framework/react/api/router/createRootRouteWithContextFunction).
    * The root context that will be provided to all routes in the route tree.
+   *
    * This can be used to provide a context to all routes in the tree without having to provide it to each route individually.
+   *
+   * Optional or required if the root route was created with [`createRootRouteWithContext()`](https://tanstack.com/router/latest/docs/framework/react/api/router/createRootRouteWithContextFunction).
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#context-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/router-context)
    */
   context?: InferRouterContext<TRouteTree>
   /**
    * A function that will be called when the router is dehydrated.
+   *
    * The return value of this function will be serialized and stored in the router's dehydrated state.
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#dehydrate-method)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/external-data-loading#critical-dehydrationhydration)
    */
   dehydrate?: () => TDehydrated
   /**
    * A function that will be called when the router is hydrated.
+   *
    * The return value of this function will be serialized and stored in the router's dehydrated state.
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#hydrate-method)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/external-data-loading#critical-dehydrationhydration)
    */
   hydrate?: (dehydrated: TDehydrated) => void
   /**
    * An array of route masks that will be used to mask routes in the route tree.
+   *
    * Route masking is when you display a route at a different path than the one it is configured to match, like a modal popup that when shared will unmask to the modal's content instead of the modal's context.
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#routemasks-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/route-masking)
    */
   routeMasks?: Array<RouteMask<TRouteTree>>
   /**
-   * Defaults to `false`
    * If `true`, route masks will, by default, be removed when the page is reloaded.
+   *
    * This can be overridden on a per-mask basis by setting the `unmaskOnReload` option on the mask, or on a per-navigation basis by setting the `unmaskOnReload` option in the `Navigate` options.
+   *
+   * @default false
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#unmaskonreload-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/route-masking#unmasking-on-page-reload)
    */
   unmaskOnReload?: boolean
   /**
    * A component that will be used to wrap the entire router.
+   *
    * This is useful for providing a context to the entire router.
+   *
    * Only non-DOM-rendering components like providers should be used, anything else will cause a hydration error.
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#wrap-property)
    */
   Wrap?: (props: { children: any }) => React.JSX.Element
   /**
    * A component that will be used to wrap the inner contents of the router.
+   *
    * This is useful for providing a context to the inner contents of the router where you also need access to the router context and hooks.
+   *
    * Only non-DOM-rendering components like providers should be used, anything else will cause a hydration error.
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#innerwrap-property)
    */
   InnerWrap?: (props: { children: any }) => React.JSX.Element
   /**
-   * @deprecated
    * Use `notFoundComponent` instead.
+   *
+   * @deprecated
    * See https://tanstack.com/router/v1/docs/guide/not-found-errors#migrating-from-notfoundroute for more info.
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#notfoundroute-property)
    */
   notFoundRoute?: AnyRoute
   /**
-   * Defaults to `NotFound`
    * The default `notFoundComponent` a route should use if no notFound component is provided.
+   *
+   * @default NotFound
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultnotfoundcomponent-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/not-found-errors#default-router-wide-not-found-handling)
    */
   defaultNotFoundComponent?: NotFoundRouteComponent
   /**
    * The transformer that will be used when sending data between the server and the client during SSR.
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#transformer-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/ssr#data-transformers)
    */
   transformer?: RouterTransformer
   /**
    * The serializer object that will be used to determine how errors are serialized and deserialized between the server and the client.
+   *
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#errorserializer-property)
    */
   errorSerializer?: RouterErrorSerializer<TSerializedError>
   /**
-   * Defaults to `never`
    * Configures how trailing slashes are treated.
-   * `'always'` will add a trailing slash if not present, `'never'` will remove the trailing slash if present and `'preserve'` will not modify the trailing slash.
+   *
+   * - `'always'` will add a trailing slash if not present
+   * - `'never'` will remove the trailing slash if present
+   * - `'preserve'` will not modify the trailing slash.
+   *
+   * @default 'never'
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#trailingslash-property)
    */
   trailingSlash?: TTrailingSlashOption
   /**
-   * Defaults to `typeof document !== 'undefined'`
    * While usually automatic, sometimes it can be useful to force the router into a server-side state, e.g. when using the router in a non-browser environment that has access to a global.document object.
+   *
+   * @default typeof document !== 'undefined'
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#isserver property)
    */
   isServer?: boolean

package/src/utils.ts

@@ -372,3 +372,87 @@ export function usePrevious<T>(value: T): T | null {
   // 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, { rootMargin: '10px' }, {}, (entry) => {
+ * return <div ref={ref} />
+ * })
+ * ```
+ */
+export function useIntersectionObserver<T extends Element>(
+  ref: React.RefObject<T>,
+  intersectionObserverOptions: IntersectionObserverInit = {},
+  options: { disabled?: boolean } = {},
+  callback: (entry: IntersectionObserverEntry | undefined) => void,
+): IntersectionObserver | null {
+  const isIntersectionObserverAvailable = React.useRef(
+    typeof IntersectionObserver === 'function',
+  )
+
+  const observerRef = React.useRef<IntersectionObserver | null>(null)
+
+  React.useEffect(() => {
+    if (
+      !ref.current ||
+      !isIntersectionObserverAvailable.current ||
+      options.disabled
+    ) {
+      return
+    }
+
+    observerRef.current = new IntersectionObserver(([entry]) => {
+      callback(entry)
+    }, intersectionObserverOptions)
+
+    observerRef.current.observe(ref.current)
+
+    return () => {
+      observerRef.current?.disconnect()
+    }
+  }, [intersectionObserverOptions, options, ref, callback])
+
+  return observerRef.current
+}
+
+/**
+ * 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.useEffect(() => {
+    if (!ref) return
+    if (typeof ref === 'function') {
+      ref(innerRef.current)
+    } else {
+      ref.current = innerRef.current
+    }
+  })
+
+  return innerRef
+}