Skip to content

docs(api): add some extra reference links #14024

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: dev
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/react-router/dom-export.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,5 @@

export type { RouterProviderProps } from "./lib/dom-export/dom-router-provider";
export { RouterProvider } from "./lib/dom-export/dom-router-provider";
export type { HydratedRouterProps } from "./lib/dom-export/hydrated-router";
export { HydratedRouter } from "./lib/dom-export/hydrated-router";
5 changes: 3 additions & 2 deletions packages/react-router/lib/components.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -580,7 +580,8 @@ export interface MemoryRouterProps {
* @param {MemoryRouterProps.children} props.children n/a
* @param {MemoryRouterProps.initialEntries} props.initialEntries n/a
* @param {MemoryRouterProps.initialIndex} props.initialIndex n/a
* @returns A declarative in memory router for client side routing.
* @returns A declarative in-memory {@link Router | `<Router>`} for client-side
* routing.
*/
export function MemoryRouter({
basename,
Expand Down Expand Up @@ -1007,7 +1008,7 @@ export interface RouterProps {
*/
location: Partial<Location> | string;
/**
* The type of navigation that triggered this location change.
* The type of navigation that triggered this `location` change.
* Defaults to {@link NavigationType.Pop}.
*/
navigationType?: NavigationType;
Expand Down
4 changes: 4 additions & 0 deletions packages/react-router/lib/dom-export/dom-router-provider.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,12 @@ import * as ReactDOM from "react-dom";
import type { RouterProviderProps as BaseRouterProviderProps } from "react-router";
import { RouterProvider as BaseRouterProvider } from "react-router";

// FIXME: We now have two `RouterProviderProps` type, one in `react-router` and
// one in `react-router/dom`.
export type RouterProviderProps = Omit<BaseRouterProviderProps, "flushSync">;

// FIXME: We now have two `RouterProvider` components, one in `react-router` and
// one in `react-router/dom`.
export function RouterProvider(props: Omit<RouterProviderProps, "flushSync">) {
return <BaseRouterProvider flushSync={ReactDOM.flushSync} {...props} />;
}
24 changes: 17 additions & 7 deletions packages/react-router/lib/dom-export/hydrated-router.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -209,24 +209,34 @@ function createHydratedRouter({
return router;
}

interface HydratedRouterProps {
/**
* Props for the {@link HydratedRouter} component.
*
* @category Types
*/
export interface HydratedRouterProps {
/**
* Context object to passed through to `createBrowserRouter` and made available
* to `clientLoader`/`clientActon` functions
* Context object to be passed through to {@link createBrowserRouter} and made
* available to
* [`clientAction`](../../start/framework/route-module#clientAction)/[`clientLoader`](../../start/framework/route-module#clientLoader)
* functions
*/
unstable_getContext?: RouterInit["unstable_getContext"];
}

// TODO: Reference `HydratedRouterProps` in the `HydratedRouter` JSDoc
// @param {HydratedRouterProps.unstable_getContext} props.unstable_getContext n/a
/**
* Framework-mode router component to be used to to hydrate a router from a
* `ServerRouter`. See [`entry.client.tsx`](../api/framework-conventions/entry.client.tsx).
* Framework-mode router component to be used to hydrate a router from a
* {@link ServerRouter}. See [`entry.client.tsx`](../framework-conventions/entry.client.tsx).
*
* @public
* @category Framework Routers
* @mode framework
* @param props Props
* @param props.unstable_getContext Context object to passed through to
* {@link createBrowserRouter} and made available to `clientLoader`/`clientAction`
* @param props.unstable_getContext Context object to be passed through to
* {@link createBrowserRouter} and made available to
* [`clientAction`](../../start/framework/route-module#clientAction)/[`clientLoader`](../../start/framework/route-module#clientLoader)
* functions
* @returns A React element that represents the hydrated application.
*/
Expand Down
342 changes: 196 additions & 146 deletions packages/react-router/lib/dom/lib.tsx

Large diffs are not rendered by default.

76 changes: 54 additions & 22 deletions packages/react-router/lib/dom/server.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -36,24 +36,36 @@ import {
} from "../context";
import { useRoutesImpl } from "../hooks";

/**
* @category Types
*/
export interface StaticRouterProps {
/**
* The base URL for the static router (default: `/`)
*/
basename?: string;
/**
* The child elements to render inside the static router
*/
children?: React.ReactNode;
/**
* The {@link Location} to render the static router at (default: `/`)
*/
location: Partial<Location> | string;
}

/**
* A `<Router>` that may not navigate to any other location. This is useful
* on the server where there is no stateful UI.
* A {@link Router | `<Router>`} that may not navigate to any other {@link Location}.
* This is useful on the server where there is no stateful UI.
*
* @public
* @category Declarative Routers
* @mode declarative
* @param props Props
* @param props.basename The base URL for the static router (default: `/`)
* @param props.children The child elements to render inside the static router
* @param props.location The location to render the static router at (default: `/`)
* @returns A React element that renders the static router
* @param {StaticRouterProps.basename} props.basename n/a
* @param {StaticRouterProps.children} props.children n/a
* @param {StaticRouterProps.location} props.location n/a
* @returns A React element that renders the static {@link Router | `<Router>`}
*/
export function StaticRouter({
basename,
Expand Down Expand Up @@ -86,16 +98,34 @@ export function StaticRouter({
);
}

/**
* @category Types
*/
export interface StaticRouterProviderProps {
/**
* The {@link StaticHandlerContext} returned from {@link StaticHandler}'s
* `query`
*/
context: StaticHandlerContext;
/**
* The static {@link DataRouter} from {@link createStaticRouter}
*/
router: DataRouter;
/**
* Whether to hydrate the router on the client (default `true`)
*/
hydrate?: boolean;
/**
* The [`nonce`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/nonce)
* to use for the hydration [`<script>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script)
* tag
*/
nonce?: string;
}

/**
* A Data Router that may not navigate to any other location. This is useful
* on the server where there is no stateful UI.
* A {@link DataRouter} that may not navigate to any other {@link Location}.
* This is useful on the server where there is no stateful UI.
*
* @example
* export async function handleRequest(request: Request) {
Expand All @@ -117,11 +147,10 @@ export interface StaticRouterProviderProps {
* @category Data Routers
* @mode data
* @param props Props
* @param props.context The {@link StaticHandlerContext} returned from `staticHandler.query()`
* @param props.router The static data router from {@link createStaticRouter}
* @param props.hydrate Whether to hydrate the router on the client (default `true`)
* @param props.nonce The [`nonce`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/nonce)
* to use for the hydration `<script>` tag
* @param {StaticRouterProviderProps.context} props.context n/a
* @param {StaticRouterProviderProps.hydrate} props.hydrate n/a
* @param {StaticRouterProviderProps.nonce} props.nonce n/a
* @param {StaticRouterProviderProps.router} props.router n/a
* @returns A React element that renders the static router provider
*/
export function StaticRouterProvider({
Expand Down Expand Up @@ -292,7 +321,7 @@ type CreateStaticHandlerOptions = Omit<
* @example
* export async function handleRequest(request: Request) {
* let { query, dataRoutes } = createStaticHandler(routes);
* let context = await query(request));
* let context = await query(request);
*
* if (context instanceof Response) {
* return context;
Expand All @@ -308,11 +337,13 @@ type CreateStaticHandlerOptions = Omit<
* @public
* @category Data Routers
* @mode data
* @param routes The route objects to create a static handler for
* @param routes The {@link RouteObject | route objects} to create a static
* handler for
* @param opts Options
* @param opts.basename The base URL for the static handler (default: `/`)
* @param opts.future Future flags for the static handler
* @returns A static handler that can be used to query data for the provided routes
* @returns A static handler that can be used to query data for the provided
* routes
*/
export function createStaticHandler(
routes: RouteObject[],
Expand All @@ -325,12 +356,12 @@ export function createStaticHandler(
}

/**
* Create a static data router for server-side rendering
* Create a static {@link DataRouter} for server-side rendering
*
* @example
* export async function handleRequest(request: Request) {
* let { query, dataRoutes } = createStaticHandler(routes);
* let context = await query(request));
* let context = await query(request);
*
* if (context instanceof Response) {
* return context;
Expand All @@ -346,11 +377,12 @@ export function createStaticHandler(
* @public
* @category Data Routers
* @mode data
* @param routes The route objects to create a static data router for
* @param context The static handler context returned from `staticHandler.query()`
* @param routes The route objects to create a static {@link DataRouter} for
* @param context The {@link StaticHandlerContext} returned from {@link StaticHandler}'s
* `query`
* @param opts Options
* @param opts.future Future flags for the static data router
* @returns A static data router that can be used to render the provided routes
* @param opts.future Future flags for the static {@link DataRouter}
* @returns A static {@link DataRouter} that can be used to render the provided routes
*/
export function createStaticRouter(
routes: RouteObject[],
Expand Down
75 changes: 47 additions & 28 deletions packages/react-router/lib/dom/ssr/components.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -215,9 +215,10 @@ function getActiveMatches(
export const CRITICAL_CSS_DATA_ATTRIBUTE = "data-react-router-critical-css";

/**
* Renders all of the `<link>` tags created by the route module
* [`links`](../../start/framework/route-module#links) export. You should render
* it inside the `<head>` of your document.
* Renders all the [`<link>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link)
* tags created by the route module's [`links`](../../start/framework/route-module#links)
* export. You should render it inside the [`<head>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head)
* of your document.
*
* @example
* import { Links } from "react-router";
Expand All @@ -236,7 +237,8 @@ export const CRITICAL_CSS_DATA_ATTRIBUTE = "data-react-router-critical-css";
* @public
* @category Components
* @mode framework
* @returns A collection of React elements for `<link>` tags
* @returns A collection of React elements for [`<link>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link)
* tags
*/
export function Links(): React.JSX.Element {
let { isSpaMode, manifest, routeModules, criticalCss } =
Expand Down Expand Up @@ -277,10 +279,10 @@ export function Links(): React.JSX.Element {
}

/**
* Renders `<link rel=prefetch|modulepreload>` tags for modules and data of
* another page to enable an instant navigation to that page.
* [`<Link prefetch>`](../../components/Link#prefetch) uses this internally, but
* you can render it to prefetch a page for any other reason.
* Renders [`<link rel=prefetch|modulepreload>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement/rel)
* tags for modules and data of another page to enable an instant navigation to
* that page. [`<Link prefetch>`](./Link#prefetch) uses this internally, but you
* can render it to prefetch a page for any other reason.
*
* For example, you may render one of this as the user types into a search field
* to prefetch search results before they click through to their selection.
Expand All @@ -294,11 +296,14 @@ export function Links(): React.JSX.Element {
* @category Components
* @mode framework
* @param props Props
* @param props.page The absolute path of the page to prefetch, e.g. `/absolute/path`.
* @param props.linkProps Additional props to spread onto the
* [`<link>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/link)
* tags, such as `crossOrigin`, `integrity`, `rel`, etc.
* @returns A collection of React elements for `<link>` tags
* @param {PageLinkDescriptor.page} props.page n/a
* @param props.linkProps Additional props to spread onto the [`<link>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link)
* tags, such as [`crossOrigin`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement/crossOrigin),
* [`integrity`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement/integrity),
* [`rel`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement/rel),
* etc.
* @returns A collection of React elements for [`<link>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link)
* tags
*/
export function PrefetchPageLinks({ page, ...linkProps }: PageLinkDescriptor) {
let { router } = useDataRouterContext();
Expand Down Expand Up @@ -465,9 +470,10 @@ function PrefetchPageLinksImpl({
}

/**
* Renders all the `<meta>` tags created by the route module
* [`meta`](../../start/framework/route-module#meta) exports. You should render
* it inside the `<head>` of your HTML.
* Renders all the [`<meta>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta)
* tags created by the route module's [`meta`](../../start/framework/route-module#meta)
* export. You should render it inside the [`<head>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head)
* of your document.
*
* @example
* import { Meta } from "react-router";
Expand All @@ -485,7 +491,8 @@ function PrefetchPageLinksImpl({
* @public
* @category Components
* @mode framework
* @returns A collection of React elements for `<meta>` tags
* @returns A collection of React elements for [`<meta>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta)
* tags
*/
export function Meta(): React.JSX.Element {
let { isSpaMode, routeModules } = useFrameworkContext();
Expand Down Expand Up @@ -629,10 +636,19 @@ let isHydrated = false;
/**
* A couple common attributes:
*
* - `<Scripts crossOrigin>` for hosting your static assets on a different server than your app.
* - `<Scripts nonce>` to support a [content security policy for scripts](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src) with [nonce-sources](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources) for your `<script>` tags.
* - `<Scripts crossOrigin>` for hosting your static assets on a different
* server than your app.
* - `<Scripts nonce>` to support a [content security policy for scripts](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src)
* with [nonce-sources](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources)
* for your [`<script>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script)
* tags.
*
* You cannot pass through attributes such as `async`, `defer`, `src`, `type`, `noModule` because they are managed by React Router internally.
* You cannot pass through attributes such as [`async`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/async),
* [`defer`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/defer),
* [`noModule`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/noModule),
* [`src`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/src),
* or [`type`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/type),
* because they are managed by React Router internally.
*
* @category Types
*/
Expand All @@ -642,21 +658,22 @@ export type ScriptsProps = Omit<
| "children"
| "dangerouslySetInnerHTML"
| "defer"
| "src"
| "type"
| "noModule"
| "src"
| "suppressHydrationWarning"
| "type"
> & {
/**
* A [`nonce`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/nonce)
* attribute to render on [the `<script>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script)
* attribute to render on the [`<script>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script)
* element
*/
nonce?: string | undefined;
};

/**
* Renders the client runtime of your app. It should be rendered inside the
* [`<body>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/body)
* [`<body>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body)
* of the document.
*
* If server rendering, you can omit `<Scripts/>` and the app will work as a
Expand All @@ -680,10 +697,12 @@ export type ScriptsProps = Omit<
* @public
* @category Components
* @mode framework
* @param scriptProps Additional props to spread onto the
* [`<script>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script)
* tag, such as `crossOrigin`, `nonce`, etc.
* @returns A collection of React elements for `<script>` tags
* @param scriptProps Additional props to spread onto the [`<script>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script)
* tags, such as [`crossOrigin`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLScriptElement/crossOrigin),
* [`nonce`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/nonce),
* etc.
* @returns A collection of React elements for [`<script>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script)
* tags
*/
export function Scripts(scriptProps: ScriptsProps): React.JSX.Element | null {
let {
Expand Down
Loading