@khanacademy/wonder-blocks-data 5.0.1 → 7.0.0

package/legacy-docs.md

@@ -0,0 +1,3 @@
+Documentation for Wonder Blocks Data is now in Storybook.
+
+Either run `yarn start:storybook` locally, or visit the the stories for the `main` branch on [Chromatic](https://main--5e1bf4b385e3fb0020b7073c.chromatic.com).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-data",
-  "version": "5.0.1",
+  "version": "7.0.0",
   "design": "v1",
   "publishConfig": {
     "access": "public"
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.16.3",
-    "@khanacademy/wonder-blocks-core": "^4.2.1"
+    "@khanacademy/wonder-blocks-core": "^4.3.0"
   },
   "peerDependencies": {
     "@khanacademy/wonder-stuff-core": "^0.1.2",

package/src/__docs__/_overview_.stories.mdx

@@ -0,0 +1,18 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Overview"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# Wonder Blocks Data
+
+Wonder Blocks Data provides components, hooks, and additional APIs to make working with asynchronous requests easier, both client-side and server-side.
+
+ * [GraphQL](/docs/data-graphql--page)
+ * [Server-Side Rendering and Hydration](/docs/data-server-side-rendering-and-hydration--page)
+ * [Testing](/docs/data-testing--page)

package/src/__docs__/_overview_graphql.stories.mdx

@@ -0,0 +1,35 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / GraphQL"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# GraphQL in Wonder Blocks Data
+
+Wonder Blocks Data provides some utility types and functionality to assist in performing GraphQL requests. To use them, your React app should include the [`GqlRouter`](/docs/data-exports-gqlrouter--page) component to specify the method responsible for actually making the GraphQL requests, as well as any default context that requests should include.
+
+The [`GqlRouter`](/docs/data-exports-gqlrouter--page) component uses React context to convey this information to the [`useGql`](/docs/data-exports-usegql--page) hook, which provides a wrapper to the fetch function, allowing for simplified invocation of requests that can merge context changes with the default context as well as only provide context and variables when needed.
+
+## Testing
+
+By using the [`GqlRouter`](/docs/data-exports-gqlrouter--page) in combination with the [`mockGqlFetch()`](/docs/testing-exports-mockgqlfetch) API from Wonder Blocks Testing, you can easily mock your GraphQL responses in tests and stories.
+
+```tsx
+const mockFetch = mockGqlFetch()
+    .mockOperation(...);
+
+<GqlRouter fetch={mockFetch} defaultContext={{}}>
+    <MyComponent />
+</GqlRouter>
+```
+
+## Server-side rendering and hydration of GraphQL
+
+Server-side rendering and hydration of GraphQL data can be achieved by combining the [`useGql`](/docs/data-exports-usegql--page) hook with the [`useHydrationEffect`](/docs/data-exports/usehydrationeffect--page) hook.
+
+More details about server-side rendering with Wonder Blocks Data can be found in the [relevant overview section](/docs/data-server-side-rendering-and-hydration--page).

package/src/__docs__/_overview_ssr_.stories.mdx

@@ -0,0 +1,185 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Server-side Rendering and Hydration"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# Server-side Rendering (SSR)
+
+Wonder Blocks Data provides components, hooks, and additional APIs to make server-side rendering and hydration of asynchronous requests easier.
+
+The [`Data`](/docs/data-exports-data--page) component and the [`useHydratableEffect`](/docs/data-exports-usehydratableeffect--page) hook (which [`Data`](/docs/data-exports-data--page) uses internally) both
+support server-side rendering and hydration.
+
+These APIs have been designed to make it easy for everyday development. The developer does not need to consider the server-side process nor hydration when requiring asynchronous data. Instead, they use [`Data`](/docs/data-exports-data--page) or [`useHydratableEffect`](/docs/data-exports-usehydratableeffect--page) to get the data they need.
+
+## Integrating into server-side rendering
+
+Generally, server-side rendering has a loop that renders the page, determines what asynchronous activity needs to be resolved, resolves and caches that activity, then renders again, ensuring that as much of the page as possible has been rendered.
+
+In order for the requests made through [`Data`](/docs/data-exports-data--page) and [`useHydratableEffect`](/docs/data-exports-usehydratableeffect--page) use to be fulfilled on the server and subsequently hydrated on the client, the server responsible for rendering the page must be modified to track and capture the requests and their responses.
+
+First, Wonder Blocks Data has to be told to work in server-side mode:
+
+```ts
+import {Server} from "@khanacademy/wonder-blocks-core";
+
+Server.setServerSide();
+```
+
+By setting Wonder Blocks into server mode, requests will not be fulfilled during rendering (there would be no point since server-side rendering does not mount components and as such, cannot update the rendered component tree with the result of asynchronous requests). Instead, we are now ready to track these requests.
+
+### Tracking and fulfilling requests
+
+To track the requests, the React node being rendered must be wrapped in the [`TrackData`](/docs/data-exports-trackdata--page) component.
+
+```tsx
+const trackedElement = (
+    <TrackData>
+        {theNodeTheClientNormallyRenders}
+    </TrackData>
+);
+```
+
+The [`TrackData`](/docs/data-exports-trackdata--page) component is responsible for capturing the requests that were made during a render of the given React node. Of course to do that, we have to render the node. Rendering is usually performed by `renderToString` from the `react-dom/server` import.
+
+```ts
+import {renderToString} from "react-dom/server";
+
+renderToString(trackedElement);
+```
+
+After each render, we want to see if there are any tracked requests needing to be fulfilled. If there are, we will want to fulfill them and render again; if there are not, we are ready to finish the page rendering and move on.
+
+To determine which path to take, we can use [`hasUnfullfilledRequests`](/docs/data-exports-hasunfulfilledrequests--page), and then based off that result, either fulfill the requests, or finish rendering our page.
+
+```ts
+if (hasUnfulfilledRequests()) {
+    await fulfillAllDataRequests();
+
+    // Render again.
+    // ...
+} else {
+    // Finish rendering the page.
+    // ...
+}
+```
+
+Internally, Wonder Blocks Data caches the responses of fulfilled requests and does not track them again. Each cycle of the rendering should occur with the same knowledge you expect the client-side to have when it performs the render, so although we want to retain our hydration cache response, we need to make sure any transient caches are cleared.
+
+Once the rendered component no longer requires any further data, the cached responses can be obtained to include in the rendered page for the client to hydrate. The hydration cache is promised by `fulfillAllDataRequests()`, regardless of whether it actually had any pending requests or not.
+
+### Putting it all together
+
+> 😱 Make sure you safely embed strings in your rendered pages to avoid injection bugs. This example is brief for the purposes of illustration.
+
+A function for server-side rendering with Wonder Blocks Data could look something like this.
+
+```tsx
+import {Server} from "@khanacademy/wonder-blocks-core";
+import {
+    TrackData,
+    hasUnfulfilledRequests,
+    fulfillAllDataRequests,
+    clearSharedCache,
+} from "@khanacademy/wonder-blocks-data";
+
+// Don't forget to import your app!
+import App from "./App.js";
+
+async function renderApp(): Promise<string> {
+    // Tell Wonder Blocks we are server-side.
+    Server.setServerSide();
+
+    // Wrap the app with our tracking code.
+    const trackedElement = (
+        <TrackData>
+            <App />
+        </TrackData>
+    );
+
+    // Now, loop around rendering and fulfilling until we have nothing left
+    // to fulfill.
+    let hydrationCache = null;
+    let renderedComponent = null;
+    do {
+        /*
+         * Each render has to be isolated, so we have to make sure we clear the
+         * shared cache used by the `useSharedCache` hook as this is transient
+         * cache that does not itself get directly hydrated.
+         */
+        clearSharedCache();
+
+        // Render the tracked component.
+        renderedComponent = renderToString(trackedElement);
+
+        if (hasUnfulfilledRequests()) {
+            // Fulfill any pending requests.
+            await fulfillAllDataRequests();
+
+            // We can't leave the loop yet as we want to render the element
+            // again with the newly fulfilled data.
+            continue;
+        }
+
+
+        // We rendered with all the data fulfilled, so we can grab the
+        // hydration cache contents and exit the loop now.
+        hydrationCache = await fulfillAllDataRequests();
+    } while (hydrationCache == null);
+
+    // Finally, render the page with our hydration cache and rendered
+    // component.
+    return `
+<html>
+   <head>
+         <title>My Page</title>
+         <script>
+            window.__WONDER_BLOCKS_DATA__ = ${safeStringify(hydrationCache)}
+         </script>
+         <script src="hydrate.js"></script>
+   </head>
+   <body>
+      <div id="my-react-app-root">
+         ${renderedComponent}
+      </div>
+   </body>
+</html>
+`;
+}
+```
+
+The above page is simplified for clarity - you would need to make sure all your scripts, fonts, etc. get loaded into the page. However, assuming all those things get loaded, the last piece need is signified above as the script tag importing `hydrate.js` - this is the script that will hydrate the client-side rendered component.
+
+## Hydrating on the client-side
+
+Now that you have a rendered page, the client needs to be written to properly hydrate to the exact same state as the server rendered. To do this, the hydration cache that was serialized into the page as `window.__WONDER_BLOCKS_DATA__` must be injected into the Wonder Blocks Data cache before the React `hydrate` call is made.
+
+In the previous section, this was displayed as the `hydrate.js` script. Here is what that script might look like.
+
+```tsx
+import {hydrate} from "react-dom";
+import {initializeCache} from "@khanacademy/wonder-blocks-data";
+
+// Don't forget to import your app!
+import App from "./App.js";
+
+initializeCache(window._WONDER_BLOCKS_DATA_);
+
+React.hydrate(
+    // This should match whatever was passed to the server-side rendering
+    // function, renderApp, in the previous section.
+    <App />,
+
+    // The ID of the element to host the hydrated component has to match what
+    // the server-rendered page uses.
+    document.getElementById("my-react-app-root"),
+);
+```
+
+That's it! The client-side hydration is complete. Underneath the hood, the hydration cache is used to hydrate the responses that the server used to render the page. And if you render a page that was not server-side rendered, the [`Data`](/docs/data-exports-data--page) and [`useHydratableEffect`](/docs/data-exports-usehydratableeffect--page) know exactly what to do and will make the requests client-side instead.

package/src/__docs__/_overview_testing_.stories.mdx

@@ -0,0 +1,123 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Testing"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# Testing Support
+
+Wonder Blocks Data has been designed to support testing in a variety of environments including jest and storybook. In order to support the various ways in which folks need to test their code, we have considered a number of approaches to testing Wonder Blocks Data.
+
+## Spies
+If you are writing unit tests, you may just want to spy on the methods you are calling using `jest.spyOn` or similar. This can be a really easy way to intercept the request handler passed to the [`useCachedEffect`](/docs/data-exports-usecachedeffect--page) hook, for example, and check that it is the handler you expect.
+
+## Interceptors
+
+Each request used by Wonder Blocks Data has to have an identifier. The [`InterceptRequests`](/docs/data-exports-interceptrequests--page) component allows you to wrap the code under test with an interceptor. Interceptors are given the request identifier and get to choose, based off that identifier, if they want to provide their own response rather than let the original request handler deal with it.
+
+Multiple interceptors can be registered by nesting the [`InterceptRequests`](/docs/data-exports-interceptrequests--page) component as is necessary. Registered interceptors are invoked in ancestral order, with the nearest ancestor to the intercepted request being invoked first.
+
+When hooks like [`useServerEffect`](/docs/data-exports-useservereffect--page), [`useCachedEffect`](/docs/data-exports-usecachedeffect--page), or [`useHydratedEffect`](/docs/data-exports-usehydratedeffect--page) run, they get the chain of registered interceptors and chain those with the original handler in order to determine what to actually do when executing the request.
+
+This allows you to mock out requests in unit tests, stories, and other scenarios.
+
+## GqlRouter, mockGqlFetch, and RespondWith
+
+If you are testing GraphQL operations, you can configure [`GqlRouter`](/docs/data-exports-gqlrouter--page) with your own function for the `fetch` prop. However, crafting the right response to give
+the result you want is a bit tricky.
+
+```tsx
+const myFakeGqlFetch = (
+    operation: GqlOperation<TData, TVariables>,
+    variables: ?TVariables,
+    context: TContext,
+): Promise<Response> {
+    if (operation.id === "myQuery" && variables?.someVar === 5) {
+        return Promise.resolve({
+            status: 200,
+            text: () =>
+                Promise.resolve(
+                    JSON.stringify({
+                        data: {
+                            myQuery: {
+                                someField: "someValue",
+                            },
+                        },
+                    }),
+                ),
+        });
+    }
+
+    return Promise.resolve({
+        status: 404,
+        text: () => Promise.resolve(JSON.stringify({})),
+    });
+}
+
+<GqlRouter fetch={myFakeGqlFetch} defaultContext={{some: "sort of context"}}>
+    <ComponentUnderTest />
+</GqlRouter>
+```
+
+As shown above, you can interrogate parts of the requested operation to decide how to respond. However, this can get cumbersome if you have GraphQL requests nested in more complex components as each test has to mock out suitable responses for each one. To help with this the Wonder Blocks Testing package provides a [`RespondWith`](/docs/testing-exports-respondwith--page) type for defining responses that fit a specific scenario, and the [`mockGqlFetch()`](/docs/testing-exports-mockgqlfetch--page) API.
+
+```tsx
+const myFakeGqlFetch = mockGqlFetch()
+    .mockOperationOnce(
+        {
+            operation: MyQueryOperation,
+            variables: {
+                someVar: 5,
+            },
+        },
+        RespondWith.success({
+            data: {
+                myQuery: {
+                    someField: "someValue",
+                },
+            },
+        }),
+    );
+
+<GqlRouter fetch={myFakeGqlFetch} defaultContext={{some: "sort of context"}}>
+    <ComponentUnderTest />
+</GqlRouter>
+```
+
+In the above example, we now only mock our specific operation once. If something
+tries to request this data a second time, it will give an error instead. Not only that, but with a little refactoring, we can create a helper to set this mock up that others can call if they need to mock our operation for their own tests.
+
+```ts
+const mockMyQuery = (mockGqlFetchFn: GqlFetchMockFn): GqlFetchMockFn =>
+    mockGqlFetchFn()
+        .mockOperationOnce(
+            {
+                operation: MyQueryOperation,
+                variables: {
+                    someVar: 5,
+                },
+            },
+            RespondWith.success({
+                data: {
+                    myQuery: {
+                        someField: "someValue",
+                    },
+                },
+            }),
+        );
+
+const myFakeGqlFetch = mockMyQuery(mockGqlFetch());
+
+<GqlRouter fetch={myFakeGqlFetch} defaultContext={{some: "sort of context"}}>
+    <ComponentUnderTest />
+</GqlRouter>
+```
+
+Now, using a compose function, multiple mocks can be setup on the same `mockGqlFetch` instance.
+
+For more details on this and other testing utilities, see the [Wonder Blocks Testing documentation](/docs/testing-overview--page).

package/src/__docs__/exports.clear-shared-cache.stories.mdx

@@ -0,0 +1,20 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / clearSharedCache()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# clearSharedCache()
+
+```ts
+clearSharedCache(scope?: string): void;
+```
+
+The `clearSharedCache` method can be used to clear the shared in-memory cache used by the [`useSharedCache`](/docs/data-exports-clearsharedcache--page) hook. Either a single scope or all scopes can be cleared.
+
+Common uses for calling this method are during [server-side rendering](/docs/data-server-side-rendering-and-hydration--page) to ensure each render cycle remains isolated, or during testing in a `beforeEach` to cover for where previous test cases may have changed the shared cache.

package/src/__docs__/exports.data-error.stories.mdx

@@ -0,0 +1,23 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / DataError"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# DataError
+
+
+```ts
+new DataError(
+    message: string,
+    kind: $Values<typeof DataErrors>,
+    options?: ErrorOptions,
+);
+```
+
+The `DataError` class is a derivation of the Wonder Blocks Core `KindError` (which is itself a derivation of `Error`). It is used by the Wonder Blocks Data framework to encapsulate errors that can occur when using its API. The different kinds of errors supported are defined by the [`DataErrors`](/docs/data-exports-dataerrors--page) export.

package/src/__docs__/exports.data-errors.stories.mdx

@@ -0,0 +1,23 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / DataErrors"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# DataErrors
+
+This export defines the error taxonomy used by Wonder Blocks Data to describe the errors that can occur. These are for use with [`DataError`](/docs/data-exports-dataerror--page).
+
+| Kind | Description |
+| ---- | ----------- |
+| `DataErrors.Unknown` | The kind of error is not known. |
+| `DataErrors.Internal` | The error is internal to the executing code. |
+| `DataErrors.InvalidInput` | There was a problem with the provided input. |
+| `DataErrors.Network` | A network error occurred. |
+| `DataErrors.Parse` | Response could not be parsed. |
+| `DataErrors.Hydrated` | An error that occurred during SSR and was hydrated from cache |

package/src/{components/data.md → __docs__/exports.data.stories.mdx}

@@ -1,3 +1,18 @@
+import {Meta} from "@storybook/addon-docs";
+import {Data} from "../index.js";
+
+<Meta
+    title="Data / Exports / Data"
+    component={Data}
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# Data
+
 The `Data` component is the frontend piece of our data architecture.
 It describes a data requirement in terms of a handler and an identifier.
 It also has props to govern hydrate behavior as well as loading and client-side
@@ -110,9 +125,6 @@ initializeCache({
     DATA: {
         data: "I'm DATA from the hydration cache"
     },
-    ERROR: {
-        error: "I'm an ERROR from hydration cache"
-    }
 });
 
 <View>
@@ -130,20 +142,5 @@ initializeCache({
             }}
         </Data>
     </View>
-    <Strut size={Spacing.small_12} />
-    <View>
-        <Body>This cache has error!</Body>
-        <Data handler={myHandler} requestId="ERROR">
-            {(result) => {
-                if (result.status !== "error") {
-                    return "If you see this, the example is broken!";
-                }
-
-                return (
-                    <BodyMonospace style={{color: Color.red}}>ERROR: {result.error}</BodyMonospace>
-                );
-            }}
-        </Data>
-    </View>
 </View>
 ```

package/src/__docs__/exports.fulfill-all-data-requests.stories.mdx

@@ -0,0 +1,24 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / fulfillAllDataRequests()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# fulfillAllDataRequests()
+
+```ts
+fulfillAllDataRequests(): Promise<ResponseCache>;
+```
+
+When performing server-side rendering (SSR), the data requests that are being made via the [`Data`](/docs/data-exports-data--page) component can be tracked by rendering the React tree inside the [`TrackData`](/docs/data-exports-trackdata--page) component. After this has occurred, the tracked requests can be fulfilled using `fulfillAllDataRequests`.
+
+This method returns a promise that resolves to a copy of the data that was cached by fulfilling the tracked requests. In the process, it clears the record of tracked requests so that new requests can be tracked and fulfilled if so required.
+
+The returned copy of the data cache can be used with the [`initializeCache`](/docs/data-exports-initializecache--page) method to prepare the data cache before a subsequent render. This is useful on the server to then SSR a more complete result, and again on the client, to rehydrate that result.
+
+More details about server-side rendering with Wonder Blocks Data can be found in the [relevant overview section](/docs/data-server-side-rendering-and-hydration--page).

package/src/__docs__/exports.gql-error.stories.mdx

@@ -0,0 +1,23 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / GqlError"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# GqlError
+
+
+```ts
+new GqlError(
+    message: string,
+    kind: $Values<typeof GqlErrors>,
+    options?: ErrorOptions,
+);
+```
+
+The `GqlError` class is a derivation of the Wonder Blocks Core `KindError` (which is itself a derivation of `Error`). It is used by the Wonder Blocks Data GraphQL framework to encapsulate errors that can occur within the GraphQL API. The different kinds of errors supported are defined by the [`GqlErrors`](/docs/data-exports-gqlerrors--page) export.

package/src/__docs__/exports.gql-errors.stories.mdx

@@ -0,0 +1,20 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / GqlErrors"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# GqlErrors
+
+This export defines the error taxonomy used by Wonder Blocks Data to describe the GraphQL-related errors that can occur with GraphQL requests. These are for use with [`GqlError`](/docs/data-exports-gqlerror--page).
+
+| Kind | Description |
+| ---- | ----------- |
+| `GqlErrors.Unknown` | The type of error is unknown. |
+| `GqlErrors.BadResponse` | Response does not have the correct structure for a GraphQL response. |
+| `GqlErrors.ErrorResult` | A valid GraphQL result with errors field in the payload. |

package/src/__docs__/exports.gql-router.stories.mdx

@@ -0,0 +1,29 @@
+import {Meta} from "@storybook/addon-docs";
+import {GqlRouter} from "../index.js";
+
+<Meta
+    title="Data / Exports / GqlRouter"
+    component={GqlRouter}
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# GqlRouter
+
+The `GqlRouter` component is used to define the default context and fetch function for performing GraphQL requests using the Wonder Blocks Data API.
+
+The [`useGql`](/docs/data-exports-usegql--page) (and therefore any hooks or components that use it) requires at least one `GqlRouter` in the component hierarchy above it or it will throw an error.
+
+The `defaultContext` is specific to the needs of your specific implementation, as is the `fetch` function. Currently, a default for the fetch function is not provided by Wonder Blocks Data and should be written to the specification of the server that will fulfill your GraphQL responses. The `fetch` function must conform to the [`GqlFetchFn<>`](/docs/data-types-gqlfetchfn--page) type.
+
+```tsx
+<GqlRouter defaultContext={{a: "1", b: "2"}} fetch={gqlFetchFn}>
+    <div>
+        The code that will ultimately use Wonder Blocks Data-based GraphQL
+        operations goes here.
+    </div>
+</GqlRouter>
+```

package/src/__docs__/exports.has-unfulfilled-requests.stories.mdx

@@ -0,0 +1,20 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / hasUnfulfilledRequests()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# hasUnfulfilledRequests()
+
+```ts
+hasUnfulfilledRequests(): boolean;
+```
+
+When performing server-side rendering (SSR), any requests that have been tracked will cause this method to return `true`. Once [`fulfillAllDataRequests`](/docs/data-exports-fulfillalldatarequests--page) has been called and the promise is settled, this method will return `false` to indicate that there are no more pending requests.
+
+More details about server-side rendering with Wonder Blocks Data can be found in the [relevant overview section](/docs/data-server-side-rendering-and-hydration--page).

package/src/{components/intercept-requests.md → __docs__/exports.intercept-requests.stories.mdx}

@@ -1,3 +1,18 @@
+import {Meta} from "@storybook/addon-docs";
+import {InterceptRequests} from "../index.js";
+
+<Meta
+    title="Data / Exports / InterceptRequests"
+    component={InterceptRequests}
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# InterceptRequests
+
 When you want to generate tests that check the loading state and
 subsequent loaded state are working correctly for your uses of `Data` you can
 use the `InterceptRequests` component. You can also use this component to
@@ -15,7 +30,7 @@ different request IDs..
 The `interceptor` intercept function has the form:
 
 ```js static
-(requestId: string) => ?Promise<?TData>;
+(requestId: string) => ?Promise<TData>;
 ```
 
 If this method returns `null`, then the next interceptor in the chain is