From 7c98a1256e0c5cea6f014f0331194b7dd27d7477 Mon Sep 17 00:00:00 2001
From: Youngteac Hong <susukang98@gmail.com>
Date: Thu, 6 Mar 2025 11:51:55 +0900
Subject: [PATCH] Add YorkieProvider, DocumentProvider and suspense hooks
 (#946)

YorkieProvider and DocumentProvider are React context providers that enable
easy integration of Yorkie clients and documents into React applications.
They also provide convenient hooks for accessing and updating shared documents
in real-time.

```tsx
<YorkieProvider apiKey={API_KEY}>
  <DocumentProvider
    docKey={DOC_KEY}
    initialRoot={{}}
  >
    <App />
  </DocumentProvider>
</YorkieProvider>

// ...

export default function App() {
  const { root, update, loading, error } = useDocument();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

// ...
}
```
---
 examples/react-todomvc/src/App.tsx            |  31 +---
 examples/react-todomvc/src/MainSection.tsx    |  23 ++-
 examples/react-todomvc/src/main.tsx           |  19 +-
 packages/react/README.md                      |  19 ++
 packages/react/package.json                   |   6 +-
 packages/react/src/DocumentProvider.tsx       | 164 ++++++++++++++++++
 packages/react/src/YorkieProvider.tsx         |  72 ++++++++
 packages/react/src/index.ts                   |  19 +-
 .../src/{useDocument.ts => useYorkieDoc.ts}   |   4 +-
 packages/react/tsconfig.json                  |   1 +
 packages/react/vite.config.js                 |   2 +
 packages/sdk/README.md                        |  21 +++
 packages/sdk/package.json                     |   3 +-
 packages/sdk/src/yorkie.ts                    |   1 +
 14 files changed, 340 insertions(+), 45 deletions(-)
 create mode 100644 packages/react/README.md
 create mode 100644 packages/react/src/DocumentProvider.tsx
 create mode 100644 packages/react/src/YorkieProvider.tsx
 rename packages/react/src/{useDocument.ts => useYorkieDoc.ts} (95%)
 create mode 100644 packages/sdk/README.md

diff --git a/examples/react-todomvc/src/App.tsx b/examples/react-todomvc/src/App.tsx
index 44a301a1e..7d0caccaa 100644
--- a/examples/react-todomvc/src/App.tsx
+++ b/examples/react-todomvc/src/App.tsx
@@ -1,46 +1,29 @@
-import { useDocument, JSONArray, JSONObject } from '@yorkie-js/react';
-import 'todomvc-app-css/index.css';
+import { JSONArray, JSONObject, useDocument } from '@yorkie-js/react';
 
 import Header from './Header';
 import MainSection from './MainSection';
 import { Todo } from './model';
 import './App.css';
 
+import 'todomvc-app-css/index.css';
+
 /**
  * `App` is the root component of the application.
  */
 export default function App() {
   const { root, update, loading, error } = useDocument<{
     todos: JSONArray<Todo>;
-  }>(
-    import.meta.env.VITE_YORKIE_API_KEY,
-    `react-todomvc-${new Date().toISOString().substring(0, 10).replace(/-/g, '')}`,
-    {
-      todos: [
-        { id: 0, text: 'Yorkie JS SDK', completed: false },
-        { id: 1, text: 'Garbage collection', completed: false },
-        { id: 2, text: 'RichText datatype', completed: false },
-      ],
-    },
-    {
-      rpcAddr: import.meta.env.VITE_YORKIE_API_ADDR,
-    },
-  );
-
-  if (loading) {
-    return <div>Loading...</div>;
-  }
+  }>();
 
-  if (error) {
-    return <div>Error: {error.message}</div>;
-  }
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
 
   const actions = {
     addTodo: (text: string) => {
       update((root) => {
         root.todos.push({
           id:
-            root.todos.reduce((maxId, todo) => Math.max(todo.id, maxId), -1) +
+            root.todos.reduce((maxID, todo) => Math.max(todo.id, maxID), -1) +
             1,
           completed: false,
           text,
diff --git a/examples/react-todomvc/src/MainSection.tsx b/examples/react-todomvc/src/MainSection.tsx
index 2e503cc54..632be24fa 100644
--- a/examples/react-todomvc/src/MainSection.tsx
+++ b/examples/react-todomvc/src/MainSection.tsx
@@ -16,9 +16,8 @@ interface MainSectionProps {
   actions: { [name: string]: Function };
 }
 
-export default function MainSection(props: MainSectionProps) {
+export default function MainSection({ todos, actions }: MainSectionProps) {
   const [filter, setFilter] = useState('SHOW_ALL');
-  const { todos, actions } = props;
   const filteredTodos = todos.filter(TODO_FILTERS[filter]);
   const completedCount = todos.reduce((count, todo) => {
     return todo.completed ? count + 1 : count;
@@ -37,17 +36,15 @@ export default function MainSection(props: MainSectionProps) {
         onChange={actions.completeAll as ChangeEventHandler}
       />
       <ul className="todo-list">
-        {
-          filteredTodos.map((todo) => (
-            <TodoItem
-              key={todo.id}
-              todo={todo}
-              editTodo={actions.editTodo}
-              deleteTodo={actions.deleteTodo}
-              completeTodo={actions.completeTodo}
-            />
-          ))
-        }
+        {filteredTodos.map((todo) => (
+          <TodoItem
+            key={todo.id}
+            todo={todo}
+            editTodo={actions.editTodo}
+            deleteTodo={actions.deleteTodo}
+            completeTodo={actions.completeTodo}
+          />
+        ))}
       </ul>
       <Footer
         completedCount={completedCount}
diff --git a/examples/react-todomvc/src/main.tsx b/examples/react-todomvc/src/main.tsx
index 7ab94a52c..0bc96eda1 100644
--- a/examples/react-todomvc/src/main.tsx
+++ b/examples/react-todomvc/src/main.tsx
@@ -1,7 +1,22 @@
-import React from 'react';
 import ReactDOM from 'react-dom/client';
 import App from './App';
+import { DocumentProvider, YorkieProvider } from '@yorkie-js/react';
+
+const initalRoot = {
+  todos: [
+    { id: 0, text: 'Yorkie JS SDK', completed: false },
+    { id: 1, text: 'Garbage collection', completed: false },
+    { id: 2, text: 'RichText datatype', completed: false },
+  ],
+};
 
 ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
-  <App />,
+  <YorkieProvider apiKey={import.meta.env.VITE_YORKIE_API_KEY}>
+    <DocumentProvider
+      docKey={`react-todomvc-${new Date().toISOString().substring(0, 10).replace(/-/g, '')}`}
+      initialRoot={initalRoot}
+    >
+      <App />
+    </DocumentProvider>
+  </YorkieProvider>,
 );
diff --git a/packages/react/README.md b/packages/react/README.md
new file mode 100644
index 000000000..12b64f37c
--- /dev/null
+++ b/packages/react/README.md
@@ -0,0 +1,19 @@
+# Yorkie React SDK
+
+Yorkie React SDK is a library that provides React hooks and components for building collaborative applications with Yorkie.
+
+## How to use React SDK
+
+To get started using Yorkie React SDK, see: https://yorkie.dev/docs/getting-started/with-react
+
+## Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
+
+## Contributors ✨
+
+Thanks goes to these incredible people:
+
+<a href="https://github.com/yorkie-team/yorkie-js-sdk/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=yorkie-team/yorkie-js-sdk" />
+</a>
diff --git a/packages/react/package.json b/packages/react/package.json
index 7e0d50fe7..3c1151690 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yorkie-js/react",
-  "version": "0.6.0",
+  "version": "0.6.1-rc",
   "description": "A set of hooks and providers for Yorkie JS SDK",
   "main": "./src/index.ts",
   "publishConfig": {
@@ -8,6 +8,10 @@
     "main": "./dist/yorkie-js-react.js",
     "typings": "./dist/yorkie-js-react.d.ts"
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
diff --git a/packages/react/src/DocumentProvider.tsx b/packages/react/src/DocumentProvider.tsx
new file mode 100644
index 000000000..50016c4c1
--- /dev/null
+++ b/packages/react/src/DocumentProvider.tsx
@@ -0,0 +1,164 @@
+/*
+ * Copyright 2025 The Yorkie Authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+} from 'react';
+import { Document, Presence, Indexable } from '@yorkie-js/sdk';
+import { useYorkie } from './YorkieProvider';
+
+type DocumentContextType<R, P extends Indexable = Indexable> = {
+  root: R;
+  presences: { clientID: string; presence: P }[];
+  update: (callback: (root: R) => void) => void;
+  loading: boolean;
+  error: Error | undefined;
+};
+
+const DocumentContext = createContext<DocumentContextType<any> | null>(null);
+
+/**
+ * `DocumentProvider` is a component that provides a document to its children.
+ * This component must be under a `YorkieProvider` component to initialize the
+ * Yorkie client properly.
+ */
+export const DocumentProvider = <R, P extends Indexable = Indexable>({
+  docKey,
+  initialRoot,
+  children,
+}: {
+  docKey: string;
+  initialRoot: R;
+  children: React.ReactNode;
+}) => {
+  const client = useYorkie();
+  const [doc, setDoc] = useState<Document<R, P> | undefined>(undefined);
+  const [loading, setLoading] = useState<boolean>(true);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [root, setRoot] = useState(initialRoot);
+  const [presences, setPresences] = useState<
+    { clientID: string; presence: any }[]
+  >([]);
+
+  useEffect(() => {
+    setLoading(true);
+    setError(undefined);
+
+    if (!client) return;
+
+    const newDoc = new Document<R, P>(docKey);
+    async function attachDocument() {
+      try {
+        await client?.attach(newDoc);
+
+        newDoc.subscribe(() => {
+          setRoot({ ...newDoc.getRoot() });
+        });
+
+        newDoc.subscribe('presence', () => {
+          setPresences(newDoc.getPresences());
+        });
+
+        setDoc(newDoc);
+        setRoot({ ...newDoc.getRoot() });
+      } catch (err) {
+        setError(
+          err instanceof Error ? err : new Error('Failed to attach document'),
+        );
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    attachDocument();
+
+    return () => {
+      client.detach(newDoc);
+    };
+  }, [client, docKey]);
+
+  const update = useCallback(
+    (callback: (root: R, presence: Presence<P>) => void) => {
+      if (!doc) {
+        return;
+      }
+
+      try {
+        doc.update(callback);
+      } catch (err) {
+        setError(
+          err instanceof Error ? err : new Error('Failed to update document'),
+        );
+      }
+    },
+    [doc],
+  );
+
+  return (
+    <DocumentContext.Provider
+      value={{ root, presences, update, loading, error }}
+    >
+      {children}
+    </DocumentContext.Provider>
+  );
+};
+
+/**
+ * `useDocument` is a custom hook that returns the root object and update function of the document.
+ * This hook must be used within a `DocumentProvider`.
+ */
+export const useDocument = <R, P extends Indexable = Indexable>() => {
+  const context = useContext(DocumentContext);
+  if (!context) {
+    throw new Error('useDocument must be used within a DocumentProvider');
+  }
+  return {
+    root: context.root as R,
+    presences: context.presences as { clientID: string; presence: P }[],
+    update: context.update as (
+      callback: (root: R, presence: P) => void,
+    ) => void,
+    loading: context.loading,
+    error: context.error,
+  };
+};
+
+/**
+ * `useRoot` is a custom hook that returns the root object of the document.
+ * This hook must be used within a `DocumentProvider`.
+ */
+export const useRoot = () => {
+  const context = useContext(DocumentContext);
+  if (!context) {
+    throw new Error('useRoot must be used within a DocumentProvider');
+  }
+  return { root: context.root };
+};
+
+/**
+ * `usePresences` is a custom hook that returns the presences of the document.
+ */
+export const usePresences = () => {
+  const context = useContext(DocumentContext);
+  if (!context) {
+    throw new Error('usePresences must be used within a DocumentProvider');
+  }
+  return context.presences;
+};
diff --git a/packages/react/src/YorkieProvider.tsx b/packages/react/src/YorkieProvider.tsx
new file mode 100644
index 000000000..554de95a4
--- /dev/null
+++ b/packages/react/src/YorkieProvider.tsx
@@ -0,0 +1,72 @@
+/*
+ * Copyright 2025 The Yorkie Authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  createContext,
+  PropsWithChildren,
+  useContext,
+  useEffect,
+  useState,
+} from 'react';
+import { Client } from '@yorkie-js/sdk';
+
+const YorkieContext = createContext<{ client: Client | undefined }>({
+  client: undefined,
+});
+
+/**
+ * `YorkieProviderProps` is a set of properties for `YorkieProvider`.
+ */
+interface YorkieProviderProps {
+  apiKey: string;
+  rpcAddr?: string;
+}
+
+/**
+ * `YorkieProvider` is a component that provides the Yorkie client to its children.
+ * It initializes the Yorkie client with the given API key and RPC address.
+ */
+export const YorkieProvider: React.FC<
+  PropsWithChildren<YorkieProviderProps>
+> = ({ apiKey, rpcAddr = 'https://api.yorkie.dev', children }) => {
+  const [client, setClient] = useState<Client | undefined>(undefined);
+
+  useEffect(() => {
+    async function initClient() {
+      const newClient = new Client(rpcAddr, {
+        apiKey,
+      });
+      await newClient.activate();
+      setClient(newClient);
+    }
+    initClient();
+
+    return () => {
+      client?.deactivate({ keepalive: true });
+    };
+  }, [apiKey, rpcAddr]);
+
+  return (
+    <YorkieContext.Provider value={{ client }}>
+      {children}
+    </YorkieContext.Provider>
+  );
+};
+
+export const useYorkie = () => {
+  const context = useContext(YorkieContext);
+  return context?.client;
+};
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index b621f5574..03c1d1e1f 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -15,7 +15,22 @@
  */
 
 import type { JSONArray, JSONObject } from '@yorkie-js/sdk';
-import { useDocument } from './useDocument';
 
-export { useDocument };
+import { useYorkieDoc } from './useYorkieDoc';
+import { YorkieProvider } from './YorkieProvider';
+import {
+  DocumentProvider,
+  useDocument,
+  useRoot,
+  usePresences,
+} from './DocumentProvider';
+
 export type { JSONArray, JSONObject };
+export {
+  YorkieProvider,
+  DocumentProvider,
+  useDocument,
+  useRoot,
+  usePresences,
+  useYorkieDoc,
+};
diff --git a/packages/react/src/useDocument.ts b/packages/react/src/useYorkieDoc.ts
similarity index 95%
rename from packages/react/src/useDocument.ts
rename to packages/react/src/useYorkieDoc.ts
index a214323e0..9307d9e4c 100644
--- a/packages/react/src/useDocument.ts
+++ b/packages/react/src/useYorkieDoc.ts
@@ -18,14 +18,14 @@ import { useCallback, useEffect, useState } from 'react';
 import { Client, Document } from '@yorkie-js/sdk';
 
 /**
- * `useDocument` is a custom hook that returns the root object of the document.
+ * `useYorkieDoc` is a custom hook that initializes a Yorkie client and attaches a document.
  *
  * @param apiKey
  * @param docKey
  * @param initialRoot
  * @returns
  */
-export function useDocument<T>(
+export function useYorkieDoc<T>(
   apiKey: string,
   docKey: string,
   initialRoot: T,
diff --git a/packages/react/tsconfig.json b/packages/react/tsconfig.json
index 0d2b11a0e..7db391fa3 100644
--- a/packages/react/tsconfig.json
+++ b/packages/react/tsconfig.json
@@ -6,6 +6,7 @@
     "lib": ["ES2020", "DOM"],
     "skipLibCheck": true,
     "outDir": "./lib",
+    "jsx": "react-jsx",
 
     /* Bundler mode */
     "moduleResolution": "node",
diff --git a/packages/react/vite.config.js b/packages/react/vite.config.js
index ea1b3dab2..35e2bcd5a 100644
--- a/packages/react/vite.config.js
+++ b/packages/react/vite.config.js
@@ -1,5 +1,6 @@
 import { defineConfig } from 'vite';
 import dts from 'vite-plugin-dts';
+import react from '@vitejs/plugin-react';
 import path from 'path';
 
 // https://vitejs.dev/config/
@@ -24,6 +25,7 @@ export default defineConfig({
     },
   },
   plugins: [
+    react(),
     dts({
       rollupTypes: true,
     }),
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
new file mode 100644
index 000000000..e22074834
--- /dev/null
+++ b/packages/sdk/README.md
@@ -0,0 +1,21 @@
+# Yorkie JavaScript SDK
+
+[![codecov](https://codecov.io/gh/yorkie-team/yorkie-js-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/yorkie-team/yorkie-js-sdk)
+
+The Yorkie JavaScript SDK implements the client-side libraries.
+
+## How to use JS SDK
+
+To get started using Yorkie JavaScript SDK, see: https://yorkie.dev/docs/js-sdk
+
+## Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
+
+## Contributors ✨
+
+Thanks goes to these incredible people:
+
+<a href="https://github.com/yorkie-team/yorkie-js-sdk/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=yorkie-team/yorkie-js-sdk" />
+</a>
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index a1151d917..333d91959 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -9,7 +9,8 @@
     "typings": "./dist/yorkie-js-sdk.d.ts"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc && vite build",
diff --git a/packages/sdk/src/yorkie.ts b/packages/sdk/src/yorkie.ts
index 8abcb9ccc..dff5b1e7e 100644
--- a/packages/sdk/src/yorkie.ts
+++ b/packages/sdk/src/yorkie.ts
@@ -50,6 +50,7 @@ export {
   Document,
   type ChangeInfo,
 } from '@yorkie-js-sdk/src/document/document';
+export { Presence } from '@yorkie-js-sdk/src/document/presence/presence';
 export {
   type Observer,
   type Observable,