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

Author: MichaelDeBoey

packages/react-router/dom-export.ts

@@ -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";

packages/react-router/lib/components.tsx

@@ -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,
@@ -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;

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

@@ -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} />;
 }

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

@@ -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.
  */

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

@@ -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,
@@ -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) {
@@ -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({
@@ -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;
@@ -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[],
@@ -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;
@@ -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[],

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

@@ -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";
@@ -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 } =
@@ -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.
@@ -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();
@@ -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";
@@ -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();
@@ -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
  */
@@ -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
@@ -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 {