From dd73fdd27c9b4dfcd4331c93533018be3f5cc129 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 21 Oct 2025 17:03:37 +0000 Subject: [PATCH] Add JSDoc comments to React Router components and hooks Co-authored-by: tannerlinsley --- packages/react-router/src/Asset.tsx | 4 ++ packages/react-router/src/HeadContent.tsx | 8 ++++ packages/react-router/src/ScriptOnce.tsx | 4 ++ packages/react-router/src/Scripts.tsx | 4 ++ packages/react-router/src/fileRoute.ts | 43 +++++++++++++++++++ .../react-router/src/lazyRouteComponent.tsx | 9 ++++ packages/react-router/src/router.ts | 6 +++ packages/react-router/src/useCanGoBack.ts | 7 +++ packages/react-router/src/useNavigate.tsx | 12 ++++++ packages/react-router/src/useRouter.tsx | 10 ----- packages/router-core/src/searchParams.ts | 2 + 11 files changed, 99 insertions(+), 10 deletions(-) diff --git a/packages/react-router/src/Asset.tsx b/packages/react-router/src/Asset.tsx index 37347631cf..a128930cf9 100644 --- a/packages/react-router/src/Asset.tsx +++ b/packages/react-router/src/Asset.tsx @@ -8,6 +8,10 @@ interface ScriptAttrs { suppressHydrationWarning?: boolean } +/** + * Render a managed head/body tag from a router-managed descriptor. + * Used internally by `HeadContent` and `Scripts` to materialize tags. + */ export function Asset({ tag, attrs, diff --git a/packages/react-router/src/HeadContent.tsx b/packages/react-router/src/HeadContent.tsx index 48faa5c0fd..72038dd355 100644 --- a/packages/react-router/src/HeadContent.tsx +++ b/packages/react-router/src/HeadContent.tsx @@ -4,6 +4,10 @@ import { useRouter } from './useRouter' import { useRouterState } from './useRouterState' import type { RouterManagedTag } from '@tanstack/router-core' +/** + * Compute the deduped, ordered set of head tags derived from active matches + * and SSR manifest, including title/meta/links/styles/head scripts. + */ export const useTags = () => { const router = useRouter() const nonce = router.options.ssr?.nonce @@ -187,6 +191,10 @@ export const useTags = () => { * @description The `HeadContent` component is used to render meta tags, links, and scripts for the current route. * It should be rendered in the `` of your document. */ +/** + * Render head tags for the current route tree. Place this in your document + * `` (or as high as possible) to manage title/meta/links/styles. + */ export function HeadContent() { const tags = useTags() const router = useRouter() diff --git a/packages/react-router/src/ScriptOnce.tsx b/packages/react-router/src/ScriptOnce.tsx index abf5d6bf92..3faf2379bc 100644 --- a/packages/react-router/src/ScriptOnce.tsx +++ b/packages/react-router/src/ScriptOnce.tsx @@ -1,5 +1,9 @@ import { useRouter } from './useRouter' +/** + * SSR-only utility component to emit a single inline script once per request. + * Appends an internal callback marker to signal SSR completion. + */ export function ScriptOnce({ children }: { children: string }) { const router = useRouter() if (!router.isServer) { diff --git a/packages/react-router/src/Scripts.tsx b/packages/react-router/src/Scripts.tsx index 28c05bf274..6199881d3b 100644 --- a/packages/react-router/src/Scripts.tsx +++ b/packages/react-router/src/Scripts.tsx @@ -3,6 +3,10 @@ import { useRouterState } from './useRouterState' import { useRouter } from './useRouter' import type { RouterManagedTag } from '@tanstack/router-core' +/** + * Render body scripts derived from route `scripts` and SSR manifest assets. + * Place this near the end of your document body. + */ export const Scripts = () => { const router = useRouter() const nonce = router.options.ssr?.nonce diff --git a/packages/react-router/src/fileRoute.ts b/packages/react-router/src/fileRoute.ts index 3ae180abdb..55ca9d9cd6 100644 --- a/packages/react-router/src/fileRoute.ts +++ b/packages/react-router/src/fileRoute.ts @@ -57,6 +57,17 @@ import type { UseRouteContextRoute } from './useRouteContext' * @returns A function that accepts Route options and returns a Route instance. * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createFileRouteFunction */ +/** + * Creates a file-based Route factory for a given path. + * + * Used by TanStack Router's file-based routing to associate a file with a + * route. The returned function accepts standard route options. In normal usage + * the `path` string is inserted and maintained by the `tsr` generator. + * + * @param path File path literal for the route (usually auto-generated). + * @returns A function that accepts Route options and returns a Route instance. + * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createFileRouteFunction + */ export function createFileRoute< TFilePath extends keyof FileRoutesByPath, TParentRoute extends AnyRoute = FileRoutesByPath[TFilePath]['parentRoute'], @@ -85,6 +96,10 @@ export function createFileRoute< @deprecated It's no longer recommended to use the `FileRoute` class directly. Instead, use `createFileRoute('/path/to/file')(options)` to create a file route. */ +/** + @deprecated It's no longer recommended to use the `FileRoute` class directly. + Instead, use `createFileRoute('/path/to/file')(options)` to create a file route. +*/ export class FileRoute< TFilePath extends keyof FileRoutesByPath, TParentRoute extends AnyRoute = FileRoutesByPath[TFilePath]['parentRoute'], @@ -184,6 +199,11 @@ export class FileRoute< Instead, place the loader function in the the main route file, inside the `createFileRoute('/path/to/file)(options)` options. */ +/** + @deprecated It's recommended not to split loaders into separate files. + Instead, place the loader function in the the main route file, inside the + `createFileRoute('/path/to/file)(options)` options. +*/ export function FileRouteLoader< TFilePath extends keyof FileRoutesByPath, TRoute extends FileRoutesByPath[TFilePath]['preLoaderRoute'], @@ -308,6 +328,18 @@ export class LazyRoute { * @returns A function that accepts lazy route options and returns a `LazyRoute`. * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyRouteFunction */ +/** + * Creates a lazily-configurable code-based route stub by ID. + * + * Use this for code-splitting with code-based routes. The returned function + * accepts only non-critical route options like `component`, `pendingComponent`, + * `errorComponent`, and `notFoundComponent` which are applied when the route + * is matched. + * + * @param id Route ID string literal to associate with the lazy route. + * @returns A function that accepts lazy route options and returns a `LazyRoute`. + * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyRouteFunction + */ export function createLazyRoute< TRouter extends AnyRouter = RegisteredRouter, TId extends string = string, @@ -343,6 +375,17 @@ export function createLazyRoute< * @returns A function that accepts lazy route options and returns a `LazyRoute`. * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyFileRouteFunction */ +/** + * Creates a lazily-configurable file-based route stub by file path. + * + * Use this for code-splitting with file-based routes (eg. `.lazy.tsx` files). + * The returned function accepts only non-critical route options like + * `component`, `pendingComponent`, `errorComponent`, and `notFoundComponent`. + * + * @param id File path literal for the route file. + * @returns A function that accepts lazy route options and returns a `LazyRoute`. + * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyFileRouteFunction + */ export function createLazyFileRoute< TFilePath extends keyof FileRoutesByPath, TRoute extends FileRoutesByPath[TFilePath]['preLoaderRoute'], diff --git a/packages/react-router/src/lazyRouteComponent.tsx b/packages/react-router/src/lazyRouteComponent.tsx index c679625298..ecb14be3cf 100644 --- a/packages/react-router/src/lazyRouteComponent.tsx +++ b/packages/react-router/src/lazyRouteComponent.tsx @@ -2,6 +2,15 @@ import * as React from 'react' import { isModuleNotFoundError } from '@tanstack/router-core' import type { AsyncRouteComponent } from './route' +/** + * Wrap a dynamic import to create a route component that supports + * `.preload()` and friendly reload-on-module-missing behavior. + * + * @param importer Function returning a module promise + * @param exportName Named export to use (default: `default`) + * @returns A lazy route component compatible with TanStack Router + * @link https://tanstack.com/router/latest/docs/framework/react/api/router/lazyRouteComponentFunction + */ /** * Wrap a dynamic import to create a route component that supports * `.preload()` and friendly reload-on-module-missing behavior. diff --git a/packages/react-router/src/router.ts b/packages/react-router/src/router.ts index b3a20910f8..73189391ff 100644 --- a/packages/react-router/src/router.ts +++ b/packages/react-router/src/router.ts @@ -105,6 +105,12 @@ export class Router< TRouterHistory, TDehydrated > { + /** + * React-specific Router implementation extending the framework-agnostic core. + * + * Use {@link createRouter} to construct instances. + * Pass this instance to {@link RouterProvider} to enable routing. + */ constructor( options: RouterConstructorOptions< TRouteTree, diff --git a/packages/react-router/src/useCanGoBack.ts b/packages/react-router/src/useCanGoBack.ts index 9476a9d51f..607d80e513 100644 --- a/packages/react-router/src/useCanGoBack.ts +++ b/packages/react-router/src/useCanGoBack.ts @@ -1,5 +1,12 @@ import { useRouterState } from './useRouterState' +/** + * Returns whether the router history can safely go back without exiting + * the application. Useful for render-time UI decisions. + * + * @returns boolean indicating back navigation availability. + * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useCanGoBack + */ export function useCanGoBack() { return useRouterState({ select: (s) => s.location.state.__TSR_index !== 0 }) } diff --git a/packages/react-router/src/useNavigate.tsx b/packages/react-router/src/useNavigate.tsx index 467c689c2c..bb2f31d28c 100644 --- a/packages/react-router/src/useNavigate.tsx +++ b/packages/react-router/src/useNavigate.tsx @@ -7,6 +7,18 @@ import type { RegisteredRouter, UseNavigateResult, } from '@tanstack/router-core' +/** + * Programmatic navigation hook. + * + * Returns a stable `navigate` function that updates the current location + * (pathname, search, hash, state) using TanStack Router semantics. + * + * Options: + * - `from`: Base path to resolve relative navigations from (defaults to current route). + * + * @returns A `navigate` function. + * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useNavigateHook + */ export function useNavigate< TRouter extends AnyRouter = RegisteredRouter, TDefaultFrom extends string = string, diff --git a/packages/react-router/src/useRouter.tsx b/packages/react-router/src/useRouter.tsx index 1eadfb68b5..abfefecaa3 100644 --- a/packages/react-router/src/useRouter.tsx +++ b/packages/react-router/src/useRouter.tsx @@ -3,16 +3,6 @@ import warning from 'tiny-warning' import { getRouterContext } 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 - */ /** * Access the current TanStack Router instance from React context. * Must be used within a `RouterProvider`. diff --git a/packages/router-core/src/searchParams.ts b/packages/router-core/src/searchParams.ts index f36d8e490a..b64e52c34f 100644 --- a/packages/router-core/src/searchParams.ts +++ b/packages/router-core/src/searchParams.ts @@ -1,7 +1,9 @@ import { decode, encode } from './qss' import type { AnySchema } from './validators' +/** Default `parseSearch` implementation using JSON.parse for values. */ export const defaultParseSearch = parseSearchWith(JSON.parse) +/** Default `stringifySearch` implementation using JSON.stringify for objects. */ export const defaultStringifySearch = stringifySearchWith( JSON.stringify, JSON.parse,