diff --git a/packages/router-core/src/Matches.ts b/packages/router-core/src/Matches.ts index 27ec4c67f5c..5de34b3c1a5 100644 --- a/packages/router-core/src/Matches.ts +++ b/packages/router-core/src/Matches.ts @@ -206,9 +206,34 @@ export type MakeRouteMatchUnion< > : never +/** + * The `MatchRouteOptions` type is used to describe the options that can be used when matching a route. + * + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/MatchRouteOptionsType#matchrouteoptions-type) + */ export interface MatchRouteOptions { + /** + * If `true`, will match against pending location instead of the current location. + * + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/MatchRouteOptionsType#pending-property) + */ pending?: boolean + /** + * If `true`, will match against the current location with case sensitivity. + * + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/MatchRouteOptionsType#casesensitive-property) + */ caseSensitive?: boolean + /** + * If `true`, will match against the current location's search params using a deep inclusive check. e.g. `{ a: 1 }` will match for a current location of `{ a: 1, b: 2 }`. + * + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/MatchRouteOptionsType#includesearch-property) + */ includeSearch?: boolean + /** + * If `true`, will match against the current location using a fuzzy match. e.g. `/posts` will match for a current location of `/posts/123`. + * + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/MatchRouteOptionsType#fuzzy-property) + */ fuzzy?: boolean } diff --git a/packages/router-core/src/link.ts b/packages/router-core/src/link.ts index 8db8faf8b3e..5fa5a2a5b3d 100644 --- a/packages/router-core/src/link.ts +++ b/packages/router-core/src/link.ts @@ -216,21 +216,64 @@ export type NavigateOptions< TMaskTo extends string = '.', > = ToOptions & NavigateOptionProps +/** + * The NavigateOptions type is used to describe the options that can be used when describing a navigation action in TanStack Router. + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType) + */ export interface NavigateOptionProps { - // if set to `true`, the router will scroll the element with an id matching the hash into view with default ScrollIntoViewOptions. - // if set to `false`, the router will not scroll the element with an id matching the hash into view. - // if set to `ScrollIntoViewOptions`, the router will scroll the element with an id matching the hash into view with the provided options. + /** + * If set to `true`, the router will scroll the element with an id matching the hash into view with default `ScrollIntoViewOptions`. + * If set to `false`, the router will not scroll the element with an id matching the hash into view. + * If set to `ScrollIntoViewOptions`, the router will scroll the element with an id matching the hash into view with the provided options. + * @default true + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#hashscrollintoview) + * @see [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) + */ hashScrollIntoView?: boolean | ScrollIntoViewOptions - // `replace` is a boolean that determines whether the navigation should replace the current history entry or push a new one. + /** + * `replace` is a boolean that determines whether the navigation should replace the current history entry or push a new one. + * @default false + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#replace) + */ replace?: boolean + /** + * Defaults to `true` so that the scroll position will be reset to 0,0 after the location is committed to the browser history. + * If `false`, the scroll position will not be reset to 0,0 after the location is committed to history. + * @default true + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#resetscroll) + */ resetScroll?: boolean /** @deprecated All navigations now use startTransition under the hood */ startTransition?: boolean - // if set to `true`, the router will wrap the resulting navigation in a document.startViewTransition() call. - // if set to `ViewTransitionOptions`, the router will pass the `types` field to document.startViewTransition({update: fn, types: viewTransition.types}) call + /** + * If set to `true`, the router will wrap the resulting navigation in a `document.startViewTransition()` call. + * If `ViewTransitionOptions`, route navigations will be called using `document.startViewTransition({update, types})` + * where `types` will be the strings array passed with `ViewTransitionOptions["types"]`. + * If the browser does not support viewTransition types, the navigation will fall back to normal `document.startTransition()`, same as if `true` was passed. + * + * If the browser does not support this api, this option will be ignored. + * @default false + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#viewtransition) + * @see [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition) + * @see [Google](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#view-transition-types) + */ viewTransition?: boolean | ViewTransitionOptions + /** + * If `true`, navigation will ignore any blockers that might prevent it. + * @default false + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#ignoreblocker) + */ ignoreBlocker?: boolean + /** + * If `true`, navigation to a route inside of router will trigger a full page load instead of the traditional SPA navigation. + * @default false + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#reloaddocument) + */ reloadDocument?: boolean + /** + * This can be used instead of `to` to navigate to a fully built href, e.g. pointing to an external target. + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#href) + */ href?: string } @@ -495,10 +538,30 @@ export type FromPathOption = ConstrainLiteral< RoutePaths > +/** + * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/navigation#active-options) + */ export interface ActiveOptions { + /** + * If true, the link will be active if the current route matches the `to` route path exactly (no children routes) + * @default false + */ exact?: boolean + /** + * If true, the link will only be active if the current URL hash matches the `hash` prop + * @default false + */ includeHash?: boolean + /** + * If true, the link will only be active if the current URL search params inclusively match the `search` prop + * @default true + */ includeSearch?: boolean + /** + * This modifies the `includeSearch` behavior. + * If true, properties in `search` that are explicitly `undefined` must NOT be present in the current URL search params for the link to be active. + * @default false + */ explicitUndefined?: boolean } diff --git a/packages/router-core/src/redirect.ts b/packages/router-core/src/redirect.ts index b81265d36db..51e5c617913 100644 --- a/packages/router-core/src/redirect.ts +++ b/packages/router-core/src/redirect.ts @@ -5,6 +5,9 @@ import type { PickAsRequired } from './utils' export type AnyRedirect = Redirect +/** + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RedirectType) + */ export type Redirect< TRouter extends AnyRouter = RegisteredRouter, TFrom extends RoutePaths | string = '/', @@ -17,8 +20,20 @@ export type Redirect< * @deprecated Use `statusCode` instead **/ code?: number + /** + * The HTTP status code to use when redirecting. + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RedirectType#statuscode-property) + */ statusCode?: number + /** + * If provided, will throw the redirect object instead of returning it. This can be useful in places where `throwing` in a function might cause it to have a return type of `never`. In that case, you can use `redirect({ throw: true })` to throw the redirect object instead of returning it. + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RedirectType#throw-property) + */ throw?: any + /** + * The HTTP headers to use when redirecting. + * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RedirectType#headers-property) + */ headers?: HeadersInit } & NavigateOptions