Document new React APIs in code - Part 2 of 2 (#11523)

.api-reports/api-report-react.md

@@ -547,7 +547,7 @@ type ConcastSourcesIterable<T> = Iterable<Source<T>>;
 export interface Context extends Record<string, any> {
 }
 
-// @public
+// @alpha
 export function createQueryPreloader(client: ApolloClient<any>): PreloadQueryFunction;
 
 // @public (undocumented)
@@ -1759,13 +1759,13 @@ interface QueryOptions<TVariables = OperationVariables, TData = any> {
 //
 // @public
 export interface QueryReference<TData = unknown, TVariables = unknown> {
-    // (undocumented)
+    // @internal (undocumented)
     [PROMISE_SYMBOL]: QueryRefPromise<TData>;
     // Warning: (ae-forgotten-export) The symbol "InternalQueryReference" needs to be exported by the entry point index.d.ts
     //
-    // (undocumented)
+    // @internal (undocumented)
     readonly [QUERY_REFERENCE_SYMBOL]: InternalQueryReference<TData>;
-    // (undocumented)
+    // @alpha
     toPromise(): Promise<QueryReference<TData, TVariables>>;
 }
 
@@ -2251,13 +2251,13 @@ export function useLoadableQuery<TData = unknown, TVariables extends OperationVa
     returnPartialData: true;
 }): UseLoadableQueryResult<DeepPartial<TData>, TVariables>;
 
-// @public (undocumented)
+// @public
 export function useLoadableQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options?: LoadableQueryHookOptions): UseLoadableQueryResult<TData, TVariables>;
 
 // @public (undocumented)
 export type UseLoadableQueryResult<TData = unknown, TVariables extends OperationVariables = OperationVariables> = [
-LoadQueryFunction<TVariables>,
-QueryReference<TData, TVariables> | null,
+loadQuery: LoadQueryFunction<TVariables>,
+queryRef: QueryReference<TData, TVariables> | null,
     {
     fetchMore: FetchMoreFunction<TData, TVariables>;
     refetch: RefetchFunction<TData, TVariables>;
@@ -2398,7 +2398,7 @@ interface WatchQueryOptions<TVariables extends OperationVariables = OperationVar
 // src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts
 // src/react/hooks/useBackgroundQuery.ts:29:3 - (ae-forgotten-export) The symbol "FetchMoreFunction" needs to be exported by the entry point index.d.ts
 // src/react/hooks/useBackgroundQuery.ts:30:3 - (ae-forgotten-export) The symbol "RefetchFunction" needs to be exported by the entry point index.d.ts
-// src/react/hooks/useLoadableQuery.ts:49:5 - (ae-forgotten-export) The symbol "ResetFunction" needs to be exported by the entry point index.d.ts
+// src/react/hooks/useLoadableQuery.ts:106:1 - (ae-forgotten-export) The symbol "ResetFunction" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 

.api-reports/api-report-react_hooks.md

@@ -1634,13 +1634,13 @@ interface QueryOptions<TVariables = OperationVariables, TData = any> {
 //
 // @public
 interface QueryReference<TData = unknown, TVariables = unknown> {
-    // (undocumented)
+    // @internal (undocumented)
     [PROMISE_SYMBOL]: QueryRefPromise<TData>;
     // Warning: (ae-forgotten-export) The symbol "InternalQueryReference" needs to be exported by the entry point index.d.ts
     //
-    // (undocumented)
+    // @internal (undocumented)
     readonly [QUERY_REFERENCE_SYMBOL]: InternalQueryReference<TData>;
-    // (undocumented)
+    // @alpha
     toPromise(): Promise<QueryReference<TData, TVariables>>;
 }
 
@@ -2091,13 +2091,13 @@ export function useLoadableQuery<TData = unknown, TVariables extends OperationVa
     returnPartialData: true;
 }): UseLoadableQueryResult<DeepPartial<TData>, TVariables>;
 
-// @public (undocumented)
+// @public
 export function useLoadableQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options?: LoadableQueryHookOptions): UseLoadableQueryResult<TData, TVariables>;
 
 // @public (undocumented)
 export type UseLoadableQueryResult<TData = unknown, TVariables extends OperationVariables = OperationVariables> = [
-LoadQueryFunction<TVariables>,
-QueryReference<TData, TVariables> | null,
+loadQuery: LoadQueryFunction<TVariables>,
+queryRef: QueryReference<TData, TVariables> | null,
     {
     fetchMore: FetchMoreFunction<TData, TVariables>;
     refetch: RefetchFunction<TData, TVariables>;
@@ -2234,7 +2234,7 @@ interface WatchQueryOptions<TVariables extends OperationVariables = OperationVar
 // src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts
 // src/react/hooks/useBackgroundQuery.ts:29:3 - (ae-forgotten-export) The symbol "FetchMoreFunction" needs to be exported by the entry point index.d.ts
 // src/react/hooks/useBackgroundQuery.ts:30:3 - (ae-forgotten-export) The symbol "RefetchFunction" needs to be exported by the entry point index.d.ts
-// src/react/hooks/useLoadableQuery.ts:49:5 - (ae-forgotten-export) The symbol "ResetFunction" needs to be exported by the entry point index.d.ts
+// src/react/hooks/useLoadableQuery.ts:106:1 - (ae-forgotten-export) The symbol "ResetFunction" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 

.api-reports/api-report-react_internal.md

@@ -1398,11 +1398,11 @@ interface QueryOptions<TVariables = OperationVariables, TData = any> {
 //
 // @public
 export interface QueryReference<TData = unknown, TVariables = unknown> {
-    // (undocumented)
+    // @internal (undocumented)
     [PROMISE_SYMBOL]: QueryRefPromise<TData>;
-    // (undocumented)
+    // @internal (undocumented)
     readonly [QUERY_REFERENCE_SYMBOL]: InternalQueryReference<TData>;
-    // (undocumented)
+    // @alpha
     toPromise(): Promise<QueryReference<TData, TVariables>>;
 }
 

.api-reports/api-report.md

@@ -544,7 +544,7 @@ export const concat: typeof ApolloLink.concat;
 // @public (undocumented)
 export const createHttpLink: (linkOptions?: HttpOptions) => ApolloLink;
 
-// @public
+// @alpha
 export function createQueryPreloader(client: ApolloClient<any>): PreloadQueryFunction;
 
 // @public @deprecated (undocumented)
@@ -2323,13 +2323,13 @@ export { QueryOptions }
 //
 // @public
 export interface QueryReference<TData = unknown, TVariables = unknown> {
-    // (undocumented)
+    // @internal (undocumented)
     [PROMISE_SYMBOL]: QueryRefPromise<TData>;
     // Warning: (ae-forgotten-export) The symbol "InternalQueryReference" needs to be exported by the entry point index.d.ts
     //
-    // (undocumented)
+    // @internal (undocumented)
     readonly [QUERY_REFERENCE_SYMBOL]: InternalQueryReference<TData>;
-    // (undocumented)
+    // @alpha
     toPromise(): Promise<QueryReference<TData, TVariables>>;
 }
 
@@ -2904,13 +2904,13 @@ export function useLoadableQuery<TData = unknown, TVariables extends OperationVa
     returnPartialData: true;
 }): UseLoadableQueryResult<DeepPartial<TData>, TVariables>;
 
-// @public (undocumented)
+// @public
 export function useLoadableQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options?: LoadableQueryHookOptions): UseLoadableQueryResult<TData, TVariables>;
 
 // @public (undocumented)
 export type UseLoadableQueryResult<TData = unknown, TVariables extends OperationVariables = OperationVariables> = [
-LoadQueryFunction<TVariables>,
-QueryReference<TData, TVariables> | null,
+loadQuery: LoadQueryFunction<TVariables>,
+queryRef: QueryReference<TData, TVariables> | null,
     {
     fetchMore: FetchMoreFunction<TData, TVariables>;
     refetch: RefetchFunction<TData, TVariables>;
@@ -3077,7 +3077,7 @@ interface WriteContext extends ReadMergeModifyContext {
 // src/link/http/selectHttpOptionsAndBody.ts:128:32 - (ae-forgotten-export) The symbol "HttpQueryOptions" needs to be exported by the entry point index.d.ts
 // src/react/hooks/useBackgroundQuery.ts:29:3 - (ae-forgotten-export) The symbol "FetchMoreFunction" needs to be exported by the entry point index.d.ts
 // src/react/hooks/useBackgroundQuery.ts:30:3 - (ae-forgotten-export) The symbol "RefetchFunction" needs to be exported by the entry point index.d.ts
-// src/react/hooks/useLoadableQuery.ts:49:5 - (ae-forgotten-export) The symbol "ResetFunction" needs to be exported by the entry point index.d.ts
+// src/react/hooks/useLoadableQuery.ts:106:1 - (ae-forgotten-export) The symbol "ResetFunction" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 

.prettierignore

@@ -29,6 +29,8 @@
 /docs/shared/**
 !/docs/shared/ApiDoc
 !/docs/shared/ApiDoc/**
+!/docs/shared/Overrides
+!/docs/shared/Overrides/**
 
 node_modules/
 .yalc/

docs/shared/Overrides/UseLoadableQueryResult.js

@@ -0,0 +1,58 @@
+import React from "react";
+import { useMDXComponents } from "@mdx-js/react";
+import { ManualTuple } from "../ApiDoc";
+
+const HANDLERS = `{
+  fetchMore: FetchMoreFunction<TData, TVariables>;
+  refetch: RefetchFunction<TData, TVariables>;
+  reset: ResetFunction;
+}`;
+
+const RETURN_VALUE = `[
+  loadQuery: LoadQueryFunction<TVariables>,
+  queryRef: QueryReference<TData, TVariables> | null,
+  {
+    fetchMore: FetchMoreFunction<TData, TVariables>;
+    refetch: RefetchFunction<TData, TVariables>;
+    reset: ResetFunction;
+  }
+]`;
+
+export function UseLoadableQueryResult() {
+  const MDX = useMDXComponents();
+
+  return (
+    <div>
+      <MDX.pre>
+        <code className="language-ts">{RETURN_VALUE}</code>
+      </MDX.pre>
+      A tuple of three values:
+      <ManualTuple
+        idPrefix="useloadablequery-result"
+        elements={[
+          {
+            name: "loadQuery",
+            type: "LoadQueryFunction<TVariables>",
+            description:
+              "A function used to imperatively load a query. Calling this function will create or update the `queryRef` returned by `useLoadableQuery`, which should be passed to `useReadQuery`.",
+          },
+          {
+            name: "queryRef",
+            type: "QueryReference<TData, TVariables> | null",
+            description:
+              "The `queryRef` used by `useReadQuery` to read the query result.",
+            canonicalReference: "@apollo/client!QueryReference:interface",
+          },
+          {
+            name: "handlers",
+            description:
+              "Additional handlers used for the query, such as `refetch`.",
+            type: HANDLERS,
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+UseLoadableQueryResult.propTypes = {};

docs/source/api/react/hooks.mdx

@@ -10,6 +10,8 @@ api_doc:
   - "@apollo/client!useSubscription:function(1)"
   - "@apollo/client!useApolloClient:function(1)"
   - "@apollo/client!useReactiveVar:function(1)"
+  - "@apollo/client!useLoadableQuery:function(5)"
+  - "@apollo/client!useQueryRefHandlers:function(1)"
 ---
 
 import UseFragmentOptions from '../../../shared/useFragment-options.mdx';
@@ -19,6 +21,7 @@ import UseSuspenseQueryResult from '../../../shared/useSuspenseQuery-result.mdx'
 import UseBackgroundQueryResult from '../../../shared/useBackgroundQuery-result.mdx';
 import UseReadQueryResult from '../../../shared/useReadQuery-result.mdx';
 import { FunctionDetails, PropertySignatureTable, ManualTuple, InterfaceDetails } from '../../../shared/ApiDoc';
+import { UseLoadableQueryResult } from '../../../shared/Overrides/UseLoadableQueryResult'
 
 ## The `ApolloProvider` component
 
@@ -405,6 +408,14 @@ function useReadQuery<TData>(
 
 <UseReadQueryResult />
 
+<FunctionDetails
+  canonicalReference="@apollo/client!useLoadableQuery:function(5)"
+  headingLevel={2}
+  result={<UseLoadableQueryResult />}
+/>
+
+<FunctionDetails canonicalReference="@apollo/client!useQueryRefHandlers:function(1)" headingLevel={2} />
+
 <MinVersion version="3.8.0">
 
 ## `skipToken`

docs/source/api/react/preloading.mdx

@@ -0,0 +1,11 @@
+---
+title: Preloading
+description: Apollo Client preloading API reference
+minVersion: 3.9.0
+api_doc:
+  - "@apollo/client!createQueryPreloader:function(1)"
+---
+
+import { FunctionDetails } from '../../../shared/ApiDoc';
+
+<FunctionDetails canonicalReference="@apollo/client!createQueryPreloader:function(1)" headingLevel={2} />

docs/source/config.json

@@ -80,6 +80,7 @@
       },
       "React": {
         "Hooks": "/api/react/hooks",
+        "Preloading": "/api/react/preloading",
         "Testing": "/api/react/testing",
         "SSR": "/api/react/ssr",
         "Components (deprecated)": "/api/react/components",

src/react/hooks/useLoadableQuery.ts

@@ -41,11 +41,16 @@ export type UseLoadableQueryResult<
   TData = unknown,
   TVariables extends OperationVariables = OperationVariables,
 > = [
-  LoadQueryFunction<TVariables>,
-  QueryReference<TData, TVariables> | null,
+  loadQuery: LoadQueryFunction<TVariables>,
+  queryRef: QueryReference<TData, TVariables> | null,
   {
+    /** {@inheritDoc @apollo/client!QueryResultDocumentation#fetchMore:member} */
     fetchMore: FetchMoreFunction<TData, TVariables>;
+    /** {@inheritDoc @apollo/client!QueryResultDocumentation#refetch:member} */
     refetch: RefetchFunction<TData, TVariables>;
+    /**
+     * A function that resets the `queryRef` back to `null`.
+     */
     reset: ResetFunction;
   },
 ];
@@ -98,6 +103,51 @@ export function useLoadableQuery<
   }
 ): UseLoadableQueryResult<DeepPartial<TData>, TVariables>;
 
+/**
+ * A hook for imperatively loading a query, such as responding to a user
+ * interaction.
+ *
+ * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
+ *
+ * @example
+ * ```jsx
+ * import { gql, useLoadableQuery } from "@apollo/client";
+ *
+ * const GET_GREETING = gql`
+ *   query GetGreeting($language: String!) {
+ *     greeting(language: $language) {
+ *       message
+ *     }
+ *   }
+ * `;
+ *
+ * function App() {
+ *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => loadGreeting({ language: "english" })}>
+ *         Load greeting
+ *       </button>
+ *       <Suspense fallback={<div>Loading...</div>}>
+ *         {queryRef && <Hello queryRef={queryRef} />}
+ *       </Suspense>
+ *     </>
+ *   );
+ * }
+ *
+ * function Hello({ queryRef }) {
+ *   const { data } = useReadQuery(queryRef);
+ *
+ *   return <div>{data.greeting.message}</div>;
+ * }
+ * ```
+ *
+ * @since 3.9.0
+ * @param query - A GraphQL query document parsed into an AST by `gql`.
+ * @param options - Options to control how the query is executed.
+ * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
+ */
 export function useLoadableQuery<
   TData = unknown,
   TVariables extends OperationVariables = OperationVariables,

src/react/hooks/useQueryRefHandlers.ts

@@ -36,7 +36,7 @@ export interface UseQueryRefHandlersResult<
  *   // ...
  * }
  * ```
- *
+ * @since 3.9.0
  * @param queryRef - A `QueryReference` returned from `useBackgroundQuery`, `useLoadableQuery`, or `createQueryPreloader`.
  */
 export function useQueryRefHandlers<