Skip to content

Commit 9198d9f

Browse files
docs(api): add some extra reference links (#14109)
1 parent 6661f90 commit 9198d9f

File tree

4 files changed

+97
-79
lines changed

4 files changed

+97
-79
lines changed

packages/react-router/lib/components.tsx

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -144,8 +144,11 @@ export interface MemoryRouterOpts {
144144
*/
145145
basename?: string;
146146
/**
147-
* Function to provide the initial context values for all client side
148-
* navigations/fetches
147+
* A function that returns an {@link unstable_RouterContextProvider} instance
148+
* which is provided as the `context` argument to client [`action`](../../start/data/route-object#action)s,
149+
* [`loader`](../../start/data/route-object#loader)s and [middleware](../../how-to/middleware).
150+
* This function is called to generate a fresh `context` instance on each
151+
* navigation or fetcher call.
149152
*/
150153
unstable_getContext?: RouterInit["unstable_getContext"];
151154
/**

packages/react-router/lib/dom/lib.tsx

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -139,11 +139,10 @@ export interface DOMRouterOpts {
139139
basename?: string;
140140
/**
141141
* A function that returns an {@link unstable_RouterContextProvider} instance
142-
* which is provided as the `context` argument to client
143-
* [`action`](../../start/data/route-object#action)s,
144-
* [`loader`](../../start/data/route-object#loader)s and
145-
* [`middleware`](../../how-to/middleware)s. This function is called to
146-
* generate a fresh `context` instance on each navigation or fetcher call.
142+
* which is provided as the `context` argument to client [`action`](../../start/data/route-object#action)s,
143+
* [`loader`](../../start/data/route-object#loader)s and [middleware](../../how-to/middleware).
144+
* This function is called to generate a fresh `context` instance on each
145+
* navigation or fetcher call.
147146
*/
148147
unstable_getContext?: RouterInit["unstable_getContext"];
149148
/**
@@ -175,15 +174,16 @@ export interface DOMRouterOpts {
175174
* [`clientLoader`](../../start/framework/route-module#clientLoader)), you may
176175
* want to include `loaderData` for only some routes that were loaded/rendered
177176
* on the server. This allows you to hydrate _some_ of the routes (such as the
178-
* app layout/shell) while showing a `HydrateFallback`
179-
* component and running the [`loader`](../../start/data/route-object#loader)s
180-
* for other routes during hydration.
177+
* app layout/shell) while showing a `HydrateFallback` component and running
178+
* the [`loader`](../../start/data/route-object#loader)s for other routes
179+
* during hydration.
181180
*
182181
* A route [`loader`](../../start/data/route-object#loader) will run during
183182
* hydration in two scenarios:
184183
*
185184
* 1. No hydration data is provided
186-
* In these cases the `HydrateFallback` component will render on initial hydration
185+
* In these cases the `HydrateFallback` component will render on initial
186+
* hydration
187187
* 2. The `loader.hydrate` property is set to `true`
188188
* This allows you to run the [`loader`](../../start/data/route-object#loader)
189189
* even if you did not render a fallback on initial hydration (i.e., to
@@ -245,8 +245,8 @@ export interface DOMRouterOpts {
245245
*
246246
* The `dataStrategy` function should return a key/value-object of
247247
* `routeId` -> {@link DataStrategyResult} and should include entries for any
248-
* routes where a handler was executed. A `DataStrategyResult` indicates
249-
* if the handler was successful or not based on the `DataStrategyResult.type`
248+
* routes where a handler was executed. A `DataStrategyResult` indicates if
249+
* the handler was successful or not based on the `DataStrategyResult.type`
250250
* field. If the returned `DataStrategyResult.result` is a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response),
251251
* React Router will unwrap it for you (via [`res.json`](https://developer.mozilla.org/en-US/docs/Web/API/Response/json)
252252
* or [`res.text`](https://developer.mozilla.org/en-US/docs/Web/API/Response/text)).
@@ -440,11 +440,11 @@ export interface DOMRouterOpts {
440440
* user visited.
441441
*
442442
* `patchRoutesOnNavigation` will be called anytime React Router is unable to
443-
* match a `path`. The arguments include the `path`, any partial
444-
* `matches`, and a `patch` function you can call to patch
445-
* new routes into the tree at a specific location. This method is executed
446-
* during the `loading` portion of the navigation for `GET` requests and during
447-
* the `submitting` portion of the navigation for non-`GET` requests.
443+
* match a `path`. The arguments include the `path`, any partial `matches`,
444+
* and a `patch` function you can call to patch new routes into the tree at a
445+
* specific location. This method is executed during the `loading` portion of
446+
* the navigation for `GET` requests and during the `submitting` portion of
447+
* the navigation for non-`GET` requests.
448448
*
449449
* <details>
450450
* <summary><b>Example <code>patchRoutesOnNavigation</code> Use Cases</b></summary>

packages/react-router/lib/router/utils.ts

Lines changed: 72 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -123,15 +123,17 @@ export interface unstable_RouterContext<T = unknown> {
123123
}
124124

125125
/**
126-
* Creates a type-safe context object that can be used to store and retrieve
127-
* values in middleware, [loaders](../../start/framework/route-module#loader),
128-
* and [actions](../../start/framework/route-module#action). Similar to React's
129-
* [`createContext`](https://react.dev/reference/react/createContext), but
130-
* designed for React Router's request/response lifecycle.
126+
* Creates a type-safe {@link unstable_RouterContext} object that can be used to
127+
* * store and retrieve arbitrary values in [`action`](../../start/framework/route-module#action)s,
128+
* * [`loader`](../../start/framework/route-module#loader)s, and [middleware](../../how-to/middleware).
129+
* * Similar to React's [`createContext`](https://react.dev/reference/react/createContext),
130+
* * but specifically designed for React Router's request/response lifecycle.
131131
*
132-
* If a `defaultValue` is provided, it will be returned from `context.get()` when
133-
* no value has been set for the context. Otherwise reading this context when no
134-
* value has been set will throw an error.
132+
* <docs-warning>Enable this API with the `future.unstable_middleware` flag.</docs-warning>
133+
*
134+
* If a `defaultValue` is provided, it will be returned from `context.get()`
135+
* when no value has been set for the context. Otherwise, reading this context
136+
* when no value has been set will throw an error.
135137
*
136138
* ```tsx filename=app/context.ts
137139
* import { unstable_createContext } from "react-router";
@@ -142,12 +144,12 @@ export interface unstable_RouterContext<T = unknown> {
142144
* ```
143145
*
144146
* ```tsx filename=app/middleware/auth.ts
145-
* import { userContext } from "~/context";
146147
* import { getUserFromSession } from "~/auth.server";
148+
* import { userContext } from "~/context";
147149
*
148150
* export const authMiddleware = async ({
149-
* request,
150151
* context,
152+
* request,
151153
* }) => {
152154
* const user = await getUserFromSession(request);
153155
* context.set(userContext, user);
@@ -174,10 +176,11 @@ export interface unstable_RouterContext<T = unknown> {
174176
* @category Utils
175177
* @mode framework
176178
* @mode data
177-
* @param defaultValue An optional default value for the context. This value will
178-
* be returned if no value has been set for this context.
179+
* @param defaultValue An optional default value for the context. This value
180+
* will be returned if no value has been set for this context.
179181
* @returns A {@link unstable_RouterContext} object that can be used with
180-
* `context.get()` and `context.set()` in middleware, loaders, and actions.
182+
* `context.get()` and `context.set()` in [`action`](../../start/framework/route-module#action)s,
183+
* [`loader`](../../start/framework/route-module#loader)s, and [middleware](../../how-to/middleware).
181184
*/
182185
export function unstable_createContext<T>(
183186
defaultValue?: T,
@@ -187,7 +190,7 @@ export function unstable_createContext<T>(
187190

188191
/**
189192
* Provides methods for writing/reading values in application context in a
190-
* type-safe way. Primarily for usage with [Middleware](../../how-to/middleware).
193+
* type-safe way. Primarily for usage with [middleware](../../how-to/middleware).
191194
*
192195
* @example
193196
* import {
@@ -222,11 +225,11 @@ export class unstable_RouterContextProvider {
222225
}
223226

224227
/**
225-
* Access a value from the context. If no value has been set for the
226-
* context, it will return the context's `defaultValue` if provided, or throw an
227-
* error if no `defaultValue` was set.
228+
* Access a value from the context. If no value has been set for the context,
229+
* it will return the context's `defaultValue` if provided, or throw an error
230+
* if no `defaultValue` was set.
228231
* @param context The context to get the value for
229-
* @returns The value for the context, or the contexts `defaultValue` if no
232+
* @returns The value for the context, or the context's `defaultValue` if no
230233
* value was set
231234
*/
232235
get<T>(context: unstable_RouterContext<T>): T {
@@ -242,8 +245,8 @@ export class unstable_RouterContextProvider {
242245
}
243246

244247
/**
245-
* Set a value for the context. If the context already has a value set,
246-
* this will overwrite it.
248+
* Set a value for the context. If the context already has a value set, this
249+
* will overwrite it.
247250
*
248251
* @param context The context to set the value for
249252
* @param value The value to set for the context
@@ -860,6 +863,7 @@ export function convertRoutesToDataRoutes(
860863
* @param locationArg The location to match against, either a string path or a
861864
* partial {@link Location} object
862865
* @param basename Optional base path to strip from the location before matching.
866+
* Defaults to `/`.
863867
* @returns An array of matched routes, or `null` if no matches were found.
864868
*/
865869
export function matchRoutes<
@@ -1290,13 +1294,13 @@ export function generatePath<Path extends string>(
12901294
}
12911295

12921296
/**
1293-
* A PathPattern is used to match on some portion of a URL pathname.
1297+
* Used to match on some portion of a URL pathname.
12941298
*/
12951299
export interface PathPattern<Path extends string = string> {
12961300
/**
12971301
* A string to match against a URL pathname. May contain `:id`-style segments
1298-
* to indicate placeholders for dynamic parameters. May also end with `/*` to
1299-
* indicate matching the rest of the URL pathname.
1302+
* to indicate placeholders for dynamic parameters. It May also end with `/*`
1303+
* to indicate matching the rest of the URL pathname.
13001304
*/
13011305
path: Path;
13021306
/**
@@ -1311,7 +1315,7 @@ export interface PathPattern<Path extends string = string> {
13111315
}
13121316

13131317
/**
1314-
* A PathMatch contains info about how a PathPattern matched on a URL pathname.
1318+
* Contains info about how a {@link PathPattern} matched on a URL pathname.
13151319
*/
13161320
export interface PathMatch<ParamKey extends string = string> {
13171321
/**
@@ -1343,9 +1347,9 @@ type Mutable<T> = {
13431347
* @public
13441348
* @category Utils
13451349
* @param pattern The pattern to match against the URL pathname. This can be a
1346-
* string or a {@link PathPattern} object. If a string is provided, it will
1347-
* be treated as a pattern with `caseSensitive` set to `false` and `end
1348-
* set to `true`.
1350+
* string or a {@link PathPattern} object. If a string is provided, it will be
1351+
* treated as a pattern with `caseSensitive` set to `false` and `end` set to
1352+
* `true`.
13491353
* @param pathname The URL pathname to match against the pattern.
13501354
* @returns A path match object if the pattern matches the pathname,
13511355
* or `null` if it does not match.
@@ -1516,11 +1520,12 @@ export function prependBasename({
15161520
}
15171521

15181522
/**
1519-
* Returns a resolved path object relative to the given pathname.
1523+
* Returns a resolved {@link Path} object relative to the given pathname.
15201524
*
15211525
* @public
15221526
* @category Utils
1523-
* @param to The path to resolve, either a string or a partial {@link Path} object.
1527+
* @param to The path to resolve, either a string or a partial {@link Path}
1528+
* object.
15241529
* @param fromPathname The pathname to resolve the path from. Defaults to `/`.
15251530
* @returns A {@link Path} object with the resolved pathname, search, and hash.
15261531
*/
@@ -1733,18 +1738,18 @@ export class DataWithResponseInit<D> {
17331738
}
17341739

17351740
/**
1736-
* Create "responses" that contain `status`/`headers` without forcing
1737-
* serialization into an actual `Response`
1741+
* Create "responses" that contain `headers`/`status` without forcing
1742+
* serialization into an actual [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
17381743
*
17391744
* @example
17401745
* import { data } from "react-router";
17411746
*
1742-
* export async function action({ request }) {
1747+
* export async function action({ request }: Route.ActionArgs) {
17431748
* let formData = await request.formData();
17441749
* let item = await createItem(formData);
17451750
* return data(item, {
1746-
* status: 201,
17471751
* headers: { "X-Custom-Header": "value" }
1752+
* status: 201,
17481753
* });
17491754
* }
17501755
*
@@ -1755,8 +1760,8 @@ export class DataWithResponseInit<D> {
17551760
* @param data The data to be included in the response.
17561761
* @param init The status code or a `ResponseInit` object to be included in the
17571762
* response.
1758-
* @returns A `DataWithResponseInit` instance containing the data and response
1759-
* init.
1763+
* @returns A {@link DataWithResponseInit} instance containing the data and
1764+
* response init.
17601765
*/
17611766
export function data<D>(data: D, init?: number | ResponseInit) {
17621767
return new DataWithResponseInit(
@@ -1779,13 +1784,14 @@ export type RedirectFunction = (
17791784
) => Response;
17801785

17811786
/**
1782-
* A redirect response. Sets the status code and the `Location` header.
1783-
* Defaults to "302 Found".
1787+
* A redirect [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
1788+
* Sets the status code and the [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1789+
* header. Defaults to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302).
17841790
*
17851791
* @example
17861792
* import { redirect } from "react-router";
17871793
*
1788-
* export function loader({ request }) {
1794+
* export async function loader({ request }: Route.LoaderArgs) {
17891795
* if (!isLoggedIn(request))
17901796
* throw redirect("/login");
17911797
* }
@@ -1800,7 +1806,9 @@ export type RedirectFunction = (
18001806
* @param url The URL to redirect to.
18011807
* @param init The status code or a `ResponseInit` object to be included in the
18021808
* response.
1803-
* @returns A `Response` object with the redirect status and `Location` header.
1809+
* @returns A [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1810+
* object with the redirect status and [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1811+
* header.
18041812
*/
18051813
export const redirect: RedirectFunction = (url, init = 302) => {
18061814
let responseInit = init;
@@ -1817,21 +1825,23 @@ export const redirect: RedirectFunction = (url, init = 302) => {
18171825
};
18181826

18191827
/**
1820-
* A redirect response that will force a document reload to the new location.
1821-
* Sets the status code and the `Location` header.
1822-
* Defaults to "302 Found".
1828+
* A redirect [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1829+
* that will force a document reload to the new location. Sets the status code
1830+
* and the [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1831+
* header. Defaults to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302).
18231832
*
1824-
* @example
1825-
* // routes/logout.tsx
1833+
* ```tsx filename=routes/logout.tsx
18261834
* import { redirectDocument } from "react-router";
1835+
*
18271836
* import { destroySession } from "../sessions.server";
18281837
*
1829-
* export async function action({ request }) {
1838+
* export async function action({ request }: Route.ActionArgs) {
18301839
* let session = await getSession(request.headers.get("Cookie"));
18311840
* return redirectDocument("/", {
18321841
* headers: { "Set-Cookie": await destroySession(session) }
18331842
* });
18341843
* }
1844+
* ```
18351845
*
18361846
* @public
18371847
* @category Utils
@@ -1840,7 +1850,9 @@ export const redirect: RedirectFunction = (url, init = 302) => {
18401850
* @param url The URL to redirect to.
18411851
* @param init The status code or a `ResponseInit` object to be included in the
18421852
* response.
1843-
* @returns A `Response` object with the redirect status and `Location` header.
1853+
* @returns A [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1854+
* object with the redirect status and [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1855+
* header.
18441856
*/
18451857
export const redirectDocument: RedirectFunction = (url, init) => {
18461858
let response = redirect(url, init);
@@ -1849,15 +1861,16 @@ export const redirectDocument: RedirectFunction = (url, init) => {
18491861
};
18501862

18511863
/**
1852-
* A redirect response that will perform a `history.replaceState` instead of a
1853-
* `history.pushState` for client-side navigation redirects.
1854-
* Sets the status code and the `Location` header.
1855-
* Defaults to "302 Found".
1864+
* A redirect [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1865+
* that will perform a [`history.replaceState`](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState)
1866+
* instead of a [`history.pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState)
1867+
* for client-side navigation redirects. Sets the status code and the [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1868+
* header. Defaults to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302).
18561869
*
18571870
* @example
18581871
* import { replace } from "react-router";
18591872
*
1860-
* export function loader() {
1873+
* export async function loader() {
18611874
* return replace("/new-location");
18621875
* }
18631876
*
@@ -1868,7 +1881,9 @@ export const redirectDocument: RedirectFunction = (url, init) => {
18681881
* @param url The URL to redirect to.
18691882
* @param init The status code or a `ResponseInit` object to be included in the
18701883
* response.
1871-
* @returns A `Response` object with the redirect status and `Location` header.
1884+
* @returns A [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1885+
* object with the redirect status and [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
1886+
* header.
18721887
*/
18731888
export const replace: RedirectFunction = (url, init) => {
18741889
let response = redirect(url, init);
@@ -1915,8 +1930,9 @@ export class ErrorResponseImpl implements ErrorResponse {
19151930
}
19161931

19171932
/**
1918-
* Check if the given error is an ErrorResponse generated from a 4xx/5xx
1919-
* Response thrown from an action/loader
1933+
* Check if the given error is an {@link ErrorResponse} generated from a 4xx/5xx
1934+
* [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
1935+
* thrown from an [`action`](../../start/framework/route-module#action)/[`loader`](../../start/framework/route-module#loader)
19201936
*
19211937
* @example
19221938
* import { isRouteErrorResponse } from "react-router";
@@ -1925,7 +1941,7 @@ export class ErrorResponseImpl implements ErrorResponse {
19251941
* if (isRouteErrorResponse(error)) {
19261942
* return (
19271943
* <>
1928-
* <p>Error: {{error.status}: {error.statusText}}</p>
1944+
* <p>Error: `${error.status}: ${error.statusText}`</p>
19291945
* <p>{error.data}</p>
19301946
* </>
19311947
* );
@@ -1941,7 +1957,7 @@ export class ErrorResponseImpl implements ErrorResponse {
19411957
* @mode framework
19421958
* @mode data
19431959
* @param error The error to check.
1944-
* @returns `true` if the error is an `ErrorResponse`, `false` otherwise.
1960+
* @returns `true` if the error is an {@link ErrorResponse}, `false` otherwise.
19451961
*
19461962
*/
19471963
export function isRouteErrorResponse(error: any): error is ErrorResponse {

0 commit comments

Comments
 (0)