Add JSDocs for RSC apis (#14019)

Author: brophdawg11

.eslintrc

@@ -28,7 +28,11 @@
         "packages/react-router/lib/dom/ssr/components.tsx",
         "packages/react-router/lib/dom/ssr/server.tsx",
         "packages/react-router/lib/dom-export/hydrated-router.tsx",
-        "packages/react-router/lib/dom/server.tsx"
+        "packages/react-router/lib/dom/server.tsx",
+        "packages/react-router/lib/rsc/browser.tsx",
+        "packages/react-router/lib/rsc/server.rsc.ts",
+        "packages/react-router/lib/rsc/server.ssr.tsx",
+        "packages/react-router/lib/rsc/html-stream/browser.ts",
       ],
       "plugins": ["jsdoc"],
       "rules": {

.github/workflows/docs.yml

@@ -55,6 +55,10 @@ jobs:
           pnpm run docs:jsdoc --path packages/react-router/lib/dom/ssr/server.tsx --write
           pnpm run docs:jsdoc --path packages/react-router/lib/dom-export/hydrated-router.tsx --write
           pnpm run docs:jsdoc --path packages/react-router/lib/dom/server.tsx --write
+          pnpm run docs:jsdoc --path packages/react-router/lib/rsc/browser.tsx --write
+          pnpm run docs:jsdoc --path packages/react-router/lib/rsc/server.rsc.ts --write
+          pnpm run docs:jsdoc --path packages/react-router/lib/rsc/server.ssr.tsx --write
+          pnpm run docs:jsdoc --path packages/react-router/lib/rsc/html-stream/browser.ts --write
 
       - name: 💪 Commit
         run: |

packages/react-router/index.ts

@@ -290,12 +290,16 @@ export { href } from "./lib/href";
 export type {
   BrowserCreateFromReadableStreamFunction as unstable_BrowserCreateFromReadableStreamFunction,
   EncodeReplyFunction as unstable_EncodeReplyFunction,
+  RSCHydratedRouterProps as unstable_RSCHydratedRouterProps,
 } from "./lib/rsc/browser";
 export {
   createCallServer as unstable_createCallServer,
   RSCHydratedRouter as unstable_RSCHydratedRouter,
 } from "./lib/rsc/browser";
-export type { SSRCreateFromReadableStreamFunction as unstable_SSRCreateFromReadableStreamFunction } from "./lib/rsc/server.ssr";
+export type {
+  SSRCreateFromReadableStreamFunction as unstable_SSRCreateFromReadableStreamFunction,
+  RSCStaticRouterProps as unstable_RSCStaticRouterProps,
+} from "./lib/rsc/server.ssr";
 export {
   routeRSCServerRequest as unstable_routeRSCServerRequest,
   RSCStaticRouter as unstable_RSCStaticRouter,

packages/react-router/lib/rsc/browser.tsx

@@ -61,6 +61,40 @@ type WindowWithRouterGlobals = Window &
     __routerActionID: number;
   };
 
+/**
+ * Create a React `callServer` implementation for React Router.
+ *
+ * @example
+ * import {
+ *   createFromReadableStream,
+ *   createTemporaryReferenceSet,
+ *   encodeReply,
+ *   setServerCallback,
+ * } from "@vitejs/plugin-rsc/browser";
+ * import { unstable_createCallServer as createCallServer } from "react-router";
+ *
+ * setServerCallback(
+ *   createCallServer({
+ *     createFromReadableStream,
+ *     createTemporaryReferenceSet,
+ *     encodeReply,
+ *   })
+ * );
+ *
+ * @name unstable_createCallServer
+ * @public
+ * @category RSC
+ * @mode data
+ * @param opts Options
+ * @param opts.createFromReadableStream Your `react-server-dom-xyz/client`'s
+ * `createFromReadableStream`. Used to decode payloads from the server.
+ * @param opts.createTemporaryReferenceSet A function that creates a temporary
+ * reference set for the RSC payload.
+ * @param opts.encodeReply Your `react-server-dom-xyz/client`'s `encodeReply`.
+ * Used when sending payloads to the server.
+ * @param opts.fetch Optional fetch implementation. Defaults to global `fetch`.
+ * @returns A function that can be used to call server actions.
+ */
 export function createCallServer({
   createFromReadableStream,
   createTemporaryReferenceSet,
@@ -460,19 +494,89 @@ function getFetchAndDecodeViaRSC(
   };
 }
 
+/**
+ * Props for the `unstable_RSCHydratedRouter` component.
+ * @name unstable_RSCHydratedRouterProps
+ */
+export interface RSCHydratedRouterProps {
+  /**
+   * Your `react-server-dom-xyz/client`'s `createFromReadableStream` function,
+   * used to decode payloads from the server.
+   */
+  createFromReadableStream: BrowserCreateFromReadableStreamFunction;
+  /**
+   * Optional fetch implementation.  Defaults to global `fetch`.
+   */
+  fetch?: (request: Request) => Promise<Response>;
+  /**
+   * The decoded `RSCPayload` to hydrate.
+   */
+  payload: RSCPayload;
+  /**
+   * `eager` or `lazy` - Determines if links are eagerly discovered, or delayed
+   * until clicked.
+   */
+  routeDiscovery?: "eager" | "lazy";
+  /**
+   * A function that returns an `unstable_InitialContext` object
+   * (`Map<RouterContext, unknown>`), for use in client loaders, actions and
+   * middleware.
+   */
+  unstable_getContext?: RouterInit["unstable_getContext"];
+}
+
+/**
+ * Hydrates a server rendered `RSCPayload` in the browser.
+ *
+ * @example
+ * import { startTransition, StrictMode } from "react";
+ * import { hydrateRoot } from "react-dom/client";
+ * import {
+ *   unstable_getRSCStream as getRSCStream,
+ *   unstable_RSCHydratedRouter as RSCHydratedRouter,
+ * } from "react-router";
+ * import type { unstable_RSCPayload as RSCPayload } from "react-router";
+ *
+ * createFromReadableStream(getRSCStream()).then(
+ *   (payload: RSCServerPayload) => {
+ *     startTransition(async () => {
+ *       hydrateRoot(
+ *         document,
+ *         <StrictMode>
+ *           <RSCHydratedRouter
+ *             createFromReadableStream={
+ *               createFromReadableStream
+ *             }
+ *             payload={payload}
+ *           />
+ *         </StrictMode>,
+ *         {
+ *           formState: await getFormState(payload),
+ *         }
+ *       );
+ *     });
+ *   }
+ * );
+ *
+ * @name unstable_RSCHydratedRouter
+ * @public
+ * @category RSC
+ * @mode data
+ * @param props Props
+ * @param {unstable_RSCHydratedRouterProps.createFromReadableStream} props.createFromReadableStream n/a
+ * @param {unstable_RSCHydratedRouterProps.fetch} props.fetch n/a
+ * @param {unstable_RSCHydratedRouterProps.payload} props.payload n/a
+ * @param {unstable_RSCHydratedRouterProps.routeDiscovery} props.routeDiscovery n/a
+ * @param {unstable_RSCHydratedRouterProps.unstable_getContext} props.unstable_getContext n/a
+ * @returns A hydrated router that can be used to navigate and render routes.
+ */
 export function RSCHydratedRouter({
   createFromReadableStream,
   fetch: fetchImplementation = fetch,
   payload,
   routeDiscovery = "eager",
   unstable_getContext,
-}: {
-  createFromReadableStream: BrowserCreateFromReadableStreamFunction;
-  fetch?: (request: Request) => Promise<Response>;
-  payload: RSCPayload;
-  routeDiscovery?: "eager" | "lazy";
-  unstable_getContext?: RouterInit["unstable_getContext"];
-}) {
+}: RSCHydratedRouterProps) {
   if (payload.type !== "render") throw new Error("Invalid payload type");
 
   let router = React.useMemo(

packages/react-router/lib/rsc/html-stream/browser.ts

@@ -6,7 +6,42 @@ declare global {
   }
 }
 
-export function getRSCStream() {
+/**
+ * Get the prerendered RSC stream for hydration. Usually passed directly to your
+ * `react-server-dom-xyz/client`'s `createFromReadableStream`.
+ *
+ * @example
+ * import { startTransition, StrictMode } from "react";
+ * import { hydrateRoot } from "react-dom/client";
+ * import {
+ *   unstable_getRSCStream as getRSCStream,
+ *   unstable_RSCHydratedRouter as RSCHydratedRouter,
+ * } from "react-router";
+ * import type { unstable_RSCPayload as RSCPayload } from "react-router";
+ *
+ * createFromReadableStream(getRSCStream()).then(
+ *   (payload: RSCServerPayload) => {
+ *     startTransition(async () => {
+ *       hydrateRoot(
+ *         document,
+ *         <StrictMode>
+ *           <RSCHydratedRouter ...props />
+ *         </StrictMode>,
+ *         {
+ *           // Options
+ *         }
+ *       );
+ *     });
+ *   }
+ * );
+ *
+ * @name unstable_getRSCStream
+ * @public
+ * @category RSC
+ * @mode data
+ * @returns A `ReadableStream` that contains the RSC data for hydration.
+ */
+export function getRSCStream(): ReadableStream<any> {
   let encoder = new TextEncoder();
   let streamController: ReadableStreamDefaultController<Uint8Array> | null =
     null;

packages/react-router/lib/rsc/server.rsc.ts

@@ -245,6 +245,67 @@ export type DecodeReplyFunction = (
 
 export type LoadServerActionFunction = (id: string) => Promise<Function>;
 
+/**
+ * Matches the given routes to a Request and returns a RSC Response encoding an
+ * `RSCPayload` for consumption by a RSC enabled client router.
+ *
+ * @example
+ * import {
+ *   createTemporaryReferenceSet,
+ *   decodeAction,
+ *   decodeReply,
+ *   loadServerAction,
+ *   renderToReadableStream,
+ * } from "@vitejs/plugin-rsc/rsc";
+ * import { unstable_matchRSCServerRequest as matchRSCServerRequest } from "react-router";
+ *
+ * matchRSCServerRequest({
+ *   createTemporaryReferenceSet,
+ *   decodeAction,
+ *   decodeFormState,
+ *   decodeReply,
+ *   loadServerAction,
+ *   request,
+ *   routes: routes(),
+ *   generateResponse(match) {
+ *     return new Response(
+ *       renderToReadableStream(match.payload),
+ *       {
+ *         status: match.statusCode,
+ *         headers: match.headers,
+ *       }
+ *     );
+ *   },
+ * });
+ *
+ * @name unstable_matchRSCServerRequest
+ * @public
+ * @category RSC
+ * @mode data
+ * @param opts Options
+ * @param opts.basename The basename to use when matching the request.
+ * @param opts.decodeAction Your `react-server-dom-xyz/server`'s `decodeAction`
+ * function, responsible for loading a server action.
+ * @param opts.decodeReply Your `react-server-dom-xyz/server`'s `decodeReply`
+ * function, used to decode the server function's arguments and bind them to the
+ * implementation for invocation by the router.
+ * @param opts.decodeFormState A function responsible for decoding form state for
+ * progressively enhanceable forms with `useActionState` using your
+ * `react-server-dom-xyz/server`'s `decodeFormState`.
+ * @param opts.generateResponse A function responsible for using your
+ * `renderToReadableStream` to generate a Response encoding the `RSCPayload`.
+ * @param opts.loadServerAction Your `react-server-dom-xyz/server`'s
+ * `loadServerAction` function, used to load a server action by ID.
+ * @param opts.request The request to match against.
+ * @param opts.requestContext An instance of `unstable_RouterContextProvider`
+ * that should be created per request, to be passed to loaders, actions and middleware.
+ * @param opts.routes Your route definitions.
+ * @param opts.createTemporaryReferenceSet A function that returns a temporary
+ * reference set for the request, used to track temporary references in the RSC stream.
+ * @param opts.onError An optional error handler that will be called with any
+ * errors that occur during the request processing.
+ * @returns A Response that contains the RSC data for hydration.
+ */
 export async function matchRSCServerRequest({
   createTemporaryReferenceSet,
   basename,