feat(data): add GraphQL API optimistic UI docs

cspell.json

@@ -1230,6 +1230,7 @@
     "tabs.page.html",
     "tabs.router.module",
     "taglabel",
+    "tanstack",
     "task.result",
     "taskIdentifier",
     "template.json",
@@ -1508,11 +1509,5 @@
     "kotlinx",
     "snapcraft"
   ],
-  "flagWords": [
-    "hte", 
-    "full-stack", 
-    "Full-stack", 
-    "Full-Stack",
-    "sudo",
-  ]
+  "flagWords": ["hte", "full-stack", "Full-stack", "Full-Stack", "sudo"]
 }

src/directory/directory.mjs

@@ -182,6 +182,11 @@ export const directory = {
             route: '/lib/graphqlapi/working-with-files',
             filters: ['js']
           },
+          {
+            title: 'Optimistic UI',
+            route: '/lib/graphqlapi/optimistic-ui',
+            filters: ['js']
+          },
           {
             title: 'Cancel API requests',
             route: '/lib/graphqlapi/cancel-request',

src/fragments/lib/graphqlapi/js/optimistic-ui.mdx

@@ -0,0 +1,195 @@
+The GraphQL API category can be used with [TanStack Query](https://tanstack.com/query/latest/docs/react/overview) to implement optimistic UI, allowing CRUD operations to be rendered immediately on the UI before the request roundtrip has completed.
+
+To get started, run the following in an existing Amplify project:
+
+```bash
+# Install TanStack Query
+npm i @tanstack/react-query
+
+# Select default configuration
+amplify add api              
+```
+
+When prompted, use the following schema, which can also be found under `amplify/backend/api/[name of project]/schema.graphql`:
+
+```graphql
+type RealEstateProperty @model @auth(rules: [{ allow: public }]) {
+  id: ID!
+  name: String!
+  address: String
+}
+```
+
+Save the schema and run `amplify push` to deploy the changes.
+
+Next, (at the root of your project?), add the required TanStack Query imports, and create a client:
+
+```ts
+import {
+  useQuery,
+  useMutation,
+  useQueryClient,
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
+
+// Create a client
+const queryClient = new QueryClient()
+```
+
+Next, provide the client to your app:
+
+```ts
+<QueryClientProvider client={queryClient}>
+  <App />
+</QueryClientProvider>
+```
+
+Next, within your app, access the TanStack client:
+
+```ts 
+// Access the client
+const queryClient = useQueryClient()
+```
+
+<Callout>
+
+For more details on TanStack Query, including requirements, supported browsers, and advanced usage, see the [TanStack Query documentation](https://tanstack.com/query/latest/docs/react/overview). 
+For more on Amplify GraphQL API operations, see the [API documentation](https://docs.amplify.aws/lib/graphqlapi/authz/q/platform/js/).
+
+</Callout>
+
+<Callout>
+
+For the complete working example, including required imports, and React component state management, see the [Complete Example](#complete-example) below.
+
+</Callout>
+
+## Create a query with GraphQL API and TanStack Query
+
+To create a query, use the `useQuery` hook, passing in the GraphQL API query (and variables). The following example creates a query to retrieve all records from the API.
+
+```ts
+// Queries
+const query = useQuery({ queryKey: ['todos'], queryFn: getTodos })
+```
+
+## Create a mutation with GraphQL API and TanStack Query
+
+To create a mutation, use the `useMutation` hook, passing in the GraphQL mutation (and variables). The following example creates a mutation to create a new record via the API.
+
+```ts
+// Mutations
+const mutation = useMutation({
+  mutationFn: postTodo,
+  onSuccess: () => {
+    // Invalidate and refetch
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+## Loading states, etc
+
+TODO:
+
+## Complete examples
+
+<BlockSwitcher>
+<Block name="TypeScript">
+
+```ts
+import React from "react";
+import "./App.css";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { API } from "aws-amplify";
+import * as queries from "./graphql/queries";
+import * as mutations from "./graphql/mutations";
+import { GraphQLQuery } from "@aws-amplify/api";
+import {
+  ListRealEstatePropertiesQuery,
+  RealEstateProperty,
+  CreateRealEstatePropertyInput,
+  CreateRealEstatePropertyMutation,
+} from "./API";
+
+function App() {
+  // Access the client
+  const queryClient = useQueryClient();
+
+  // Simple GraphQL API query
+  async function getRealEstateProperties() {
+    const allRealEstateProperties = await API.graphql<
+      GraphQLQuery<ListRealEstatePropertiesQuery>
+    >({
+      query: queries.listRealEstateProperties,
+    });
+  }
+
+  async function postRealEstateProperty(
+    realEstatePropertyDetails: CreateRealEstatePropertyInput
+  ) {
+    const newRealEstateProperty = await API.graphql<
+      GraphQLQuery<CreateRealEstatePropertyMutation>
+    >({
+      query: mutations.createRealEstateProperty,
+      variables: { input: realEstatePropertyDetails },
+    });
+
+    console.log(newRealEstateProperty);
+    return newRealEstateProperty;
+  }
+
+  // TanStack Queries
+  const query = useQuery({
+    queryKey: ["realEstateProperties"],
+    queryFn: getRealEstateProperties,
+  });
+
+  // TanStack Mutations
+  const mutation = useMutation({
+    mutationFn: postRealEstateProperty,
+    onSuccess: () => {
+      // Invalidate and refetch
+      queryClient.invalidateQueries({ queryKey: ["realEstateProperties"] });
+    },
+  });
+
+  return (
+    <div className="App">
+      <header className="App-header">
+        <ul>
+          {/* @ts-ignore */}
+          {query.data?.map((realEstateProperty: RealEstateProperty) => (
+            <li key={realEstateProperty.id}>{realEstateProperty.name}</li>
+          ))}
+        </ul>
+
+        <button
+          onClick={() => {
+            mutation.mutate({
+              name: "New Home 1",
+              address: "12345 Example St",
+            });
+          }}
+        >
+          Add RealEstateProperty
+        </button>
+      </header>
+    </div>
+  );
+}
+
+export default App;
+``` 
+
+</Block>
+<Block name="JavaScript">
+
+```js
+// TODO
+```
+
+</Block>
+
+</BlockSwitcher>

src/pages/lib/graphqlapi/optimistic-ui/q/platform/[platform].mdx

@@ -0,0 +1,8 @@
+export const meta = {
+  title: `Optimistic UI`,
+  description: `Learn more about implementing optimistic UI with Amplify GraphQL API.`
+};
+
+import js0 from '/src/fragments/lib/graphqlapi/js/optimistic-ui.mdx';
+
+<Fragments fragments={{ js: js0 }} />