From e9d47853f2f36667d6178752797e93501bea89d2 Mon Sep 17 00:00:00 2001
From: Gwansik Kim <gwansik.kim@gwansik.dev>
Date: Wed, 23 Oct 2024 05:37:18 +0900
Subject: [PATCH] docs: add docs for `<Mutation/>` (#1335)

# Overview

close: #1303

I have written the official documentation for `<Mutation/>`

## PR Checklist

- [x] I did below actions if need

1. I read the [Contributing
Guide](https://github.com/toss/suspensive/blob/main/CONTRIBUTING.md)
2. I added documents and tests.
---
 .../pages/en/docs/react-query/Mutation.mdx    | 93 +++++++++++++++++++
 .../src/pages/en/docs/react-query/_meta.tsx   |  1 +
 .../pages/ko/docs/react-query/Mutation.mdx    | 93 +++++++++++++++++++
 .../src/pages/ko/docs/react-query/_meta.tsx   |  1 +
 4 files changed, 188 insertions(+)
 create mode 100644 docs/suspensive.org/src/pages/en/docs/react-query/Mutation.mdx
 create mode 100644 docs/suspensive.org/src/pages/ko/docs/react-query/Mutation.mdx

diff --git a/docs/suspensive.org/src/pages/en/docs/react-query/Mutation.mdx b/docs/suspensive.org/src/pages/en/docs/react-query/Mutation.mdx
new file mode 100644
index 000000000..3d8198001
--- /dev/null
+++ b/docs/suspensive.org/src/pages/en/docs/react-query/Mutation.mdx
@@ -0,0 +1,93 @@
+import { Callout, Sandpack } from '@/components'
+
+# Mutation
+
+Similar to how [`<SuspenseQuery/>`](/docs/react-query/SuspenseQuery) allows `useSuspenseQuery` to be used at the same depth, `<Mutation/>` facilitates the use of `useMutation` at the same depth.
+
+```jsx /Mutation/
+import { Mutation } from '@suspensive/react-query'
+import { useSuspenseQuery } from '@tanstack/react-query'
+
+const PostsPage = () => {
+  const { data: posts } = useSuspenseQuery({
+    queryKey: ['posts'],
+    queryFn: () => getPosts(),
+  });
+
+  return posts.map(post => (
+    <Mutation
+      key={post.id}
+      mutationFn={({ content }: { content: string }) => api.editPost({ postId: post.id, content })}
+    >
+      {postMutation => (
+        <>
+          <div>{post.content}</div>
+          {post.comments.map(comment => (
+            <Mutation
+              key={comment.id}
+              mutationFn={({ content }: { content: string }) => api.editComment({ postId: post.id, commentId: comment.id, content })}
+            >
+              {commentMutation => (
+                <div>
+                  {postMutation.isLoading ? <Spinner/> : null}
+                  {comment.content}
+                  <textarea onChange={e => commentMutation.mutateAsync({ content: e.target.value })} />
+                </div>
+              )}
+            </Mutation>
+          ))}
+        </>
+      )}
+    </Mutation>
+  ));
+}
+```
+
+### Motivation: useMutation Creates Unnecessary Depth
+
+The existing useMutation is a hook, which leads to the creation of components like PostToUseMutation and CommentToUseMutation. This creates unnecessary depth and results in awkward component names, making the structure less flexible and harder to manage due to coupling with parent components.
+
+```jsx /useMutation/
+import { useMutation } from '@tanstack/react-query'
+
+const PostsPage = () => {
+  const posts = usePosts();
+
+  return posts.map(post => <PostToUseMutation key={post.id} post={post} />);
+};
+
+// PostToUseMutation (unnecessary name, needs to be refactored to use only useMutation)
+const PostToUseMutation = ({ post }: { post: Post }) => { // Props need to be passed to useMutation.
+  const postMutation = useMutation({
+    mutationFn: ({ content }: { content: string }) => api.editPost({ postId: post.id, content }),
+  });
+
+  if (postMutation.isLoading) {
+    return <Spinner />;
+  }
+
+  return (
+    <>
+      <div>{post.content}</div>
+      <textarea onChange={e => postMutation.mutateAsync({ content: e.target.value })} />
+      {post.comments.map(comment => (
+        <CommentToUseMutation key={comment.id} post={post} comment={comment} />
+      ))}
+    </>
+  );
+};
+
+// CommentToUseMutation (unnecessary name, needs to be refactored to use only useMutation)
+const CommentToUseMutation = ({ post, comment }: { post: Post, comment: Comment }) => { // Props need to be passed to useMutation.
+  const commentMutation = useMutation({
+    mutationFn: ({ content }: { content: string }) => api.editComment({ postId: post.id, commentId: comment.id, content }),
+  });
+
+  return (
+    <div>
+      {comment.content}
+      <textarea onChange={e => commentMutation.mutateAsync({ content: e.target.value })} />
+    </div>
+  );
+};
+```
diff --git a/docs/suspensive.org/src/pages/en/docs/react-query/_meta.tsx b/docs/suspensive.org/src/pages/en/docs/react-query/_meta.tsx
index a5e6ba5dc..1ae8aabac 100644
--- a/docs/suspensive.org/src/pages/en/docs/react-query/_meta.tsx
+++ b/docs/suspensive.org/src/pages/en/docs/react-query/_meta.tsx
@@ -19,6 +19,7 @@ export default {
   SuspenseQuery: { title: '<SuspenseQuery/>' },
   SuspenseQueries: { title: '<SuspenseQueries/>' },
   SuspenseInfiniteQuery: { title: '<SuspenseInfiniteQuery/>' },
+  Mutation: { title: '<Mutation/>' },
   PrefetchQuery: { title: '<PrefetchQuery/>' },
   PrefetchInfiniteQuery: { title: '<PrefetchInfiniteQuery/>' },
   QueryClientConsumer: { title: '<QueryClientConsumer/>' },
diff --git a/docs/suspensive.org/src/pages/ko/docs/react-query/Mutation.mdx b/docs/suspensive.org/src/pages/ko/docs/react-query/Mutation.mdx
new file mode 100644
index 000000000..d4732dfc7
--- /dev/null
+++ b/docs/suspensive.org/src/pages/ko/docs/react-query/Mutation.mdx
@@ -0,0 +1,93 @@
+import { Callout, Sandpack } from '@/components'
+
+# Mutation
+
+[`<SuspenseQuery/>`](/docs/react-query/SuspenseQuery)가 useSuspenseQuery를 같은 Depth에서 사용하게 하는 역할과 마찬가지로 `<Mutation/>`는 useMutation를 같은 Depth에서 사용하기 쉽게 하기 위한 역할을 합니다.
+
+```jsx /Mutation/
+import { Mutation } from '@suspensive/react-query'
+import { useSuspenseQuery } from '@tanstack/react-query'
+
+const PostsPage = () => {
+  const { data: posts } = useSuspenseQuery({
+    queryKey: ['posts'],
+    queryFn: () => getPosts(),
+  })
+
+  return posts.map(post => (
+    <Mutation
+      key={post.id}
+      mutationFn={({ content }: { content: string }) => api.editPost({ postId: post.id, content })}
+    >
+      {postMutation => (
+        <>
+          <div>{post.content}</div>
+          {post.comments.map(comment => (
+            <Mutation
+              key={comment.id}
+              mutationFn={({ content }: { content: string }) => api.editComment({ postId: post.id, commentId: comment.id, content })}
+            >
+              {commentMutation => (
+                <div>
+                  {postMutation.isLoading ? <Spinner/> : null}
+                  {comment.content}
+                  <textarea onChange={e => commentMutation.mutateAsync({ content: e.target.value })} />
+                </div>
+              )}
+            </Mutation>
+          ))}
+        </>
+      )}
+    </Mutation>
+  ));
+}
+```
+
+### 동기: useMutation가 불필요한 Depth를 만듦
+
+기존의 useMutation는 훅이기 때문에 PostToUseMutation, CommentToUseMutation와 같은 컴포넌트를 만들게 합니다. 이것은 불필요한 Depth를 만들고 불필요한 컴포넌트 이름, 부모 컴포넌트와 결합으로 인해 구조 변경에 유연하지 않고 어렵게 만듭니다.
+
+```jsx /useMutation/
+import { useMutation } from '@tanstack/react-query'
+
+const PostsPage = () => {
+  const posts = usePosts();
+
+  return posts.map(post => <PostToUseMutation key={post.id} post={post} />);
+};
+
+// PostToUseMutation (불필요한 이름, useMutation만 사용하도록 변경 필요)
+const PostToUseMutation = ({ post }: { post: Post }) => { // props는 useMutation을 사용하기 위해 전달되어야 합니다.
+  const postMutation = useMutation({
+    mutationFn: ({ content }: { content: string }) => api.editPost({ postId: post.id }),
+  });
+
+  if (postMutation.isLoading) {
+    return <Spinner />;
+  }
+
+  return (
+    <>
+      <div>{post.content}</div>
+      <textarea onChange={e => postMutation.mutateAsync({ content: e.target.value })} />
+      {post.comments.map(comment => (
+        <CommentToUseMutation key={comment.id} post={post} comment={comment} />
+      ))}
+    </>
+  );
+};
+
+// CommentToUseMutation (불필요한 이름, useMutation만 사용하도록 변경 필요)
+const CommentToUseMutation = ({ post, comment }: { post: Post, comment: Comment }) => { // props는 useMutation을 사용하기 위해 전달되어야 합니다.
+  const commentMutation = useMutation({
+    mutationFn: ({ content }: { content: string }) => api.editComment({ postId: post.id, commentId: comment.id, comment }),
+  });
+
+  return (
+    <div>
+      {comment.content}
+      <textarea onChange={e => commentMutation.mutateAsync({ content: e.target.value })} />
+    </div>
+  );
+};
+```
diff --git a/docs/suspensive.org/src/pages/ko/docs/react-query/_meta.tsx b/docs/suspensive.org/src/pages/ko/docs/react-query/_meta.tsx
index 3164ff5d0..255ad017e 100644
--- a/docs/suspensive.org/src/pages/ko/docs/react-query/_meta.tsx
+++ b/docs/suspensive.org/src/pages/ko/docs/react-query/_meta.tsx
@@ -17,6 +17,7 @@ export default {
   SuspenseQuery: { title: '<SuspenseQuery/>' },
   SuspenseQueries: { title: '<SuspenseQueries/>' },
   SuspenseInfiniteQuery: { title: '<SuspenseInfiniteQuery/>' },
+  Mutation: { title: '<Mutation/>' },
   PrefetchQuery: { title: '<PrefetchQuery/>' },
   PrefetchInfiniteQuery: { title: '<PrefetchInfiniteQuery/>' },
   QueryClientConsumer: { title: '<QueryClientConsumer/>' },