From 2a1d46da6f95a5ee9e3700bf916b20b33fa359ca Mon Sep 17 00:00:00 2001
From: Charles Zhao <charleszhao@silverhand.io>
Date: Mon, 23 May 2022 19:05:17 +0800
Subject: [PATCH 1/2] docs: integrate Vue SDK

---
 .../current/tutorial/integrate-sdk/vue.mdx                       | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/vue.mdx b/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/vue.mdx
index 8a0a3df26..653dc0f96 100644
--- a/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/vue.mdx
+++ b/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/vue.mdx
@@ -2,6 +2,7 @@
 sidebar_label: Vue
 ---
 
+import Admonition from '@theme/Admonition';
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 

From 7ed65b5d3d228ff587c0678d6dd8dcc670fc305d Mon Sep 17 00:00:00 2001
From: Charles Zhao <charleszhao@silverhand.io>
Date: Mon, 23 May 2022 19:07:34 +0800
Subject: [PATCH 2/2] docs: refine react sdk documentation content

---
 .../docs/tutorial/integrate-sdk/react.mdx     |   4 +
 .../tutorial/integrate-sdk/react_zh-cn.mdx    |   4 +
 .../docs/tutorial/integrate-sdk/react.mdx     |  10 +-
 .../docs/docs/tutorial/integrate-sdk/vue.mdx  |   2 +-
 .../current/tutorial/integrate-sdk/react.mdx  | 215 ++++++++----------
 5 files changed, 105 insertions(+), 130 deletions(-)

diff --git a/packages/console/src/assets/docs/tutorial/integrate-sdk/react.mdx b/packages/console/src/assets/docs/tutorial/integrate-sdk/react.mdx
index 8c1cedbd2..1287c7025 100644
--- a/packages/console/src/assets/docs/tutorial/integrate-sdk/react.mdx
+++ b/packages/console/src/assets/docs/tutorial/integrate-sdk/react.mdx
@@ -50,6 +50,7 @@ pnpm build
 </TabItem>
 </Tabs>
 </Step>
+
 <Step
   title="Initiate LogtoClient"
   subtitle="1 step"
@@ -95,6 +96,7 @@ const App = () => {
 ```
 
 </Step>
+
 <Step
   title="Sign In"
   subtitle="2 steps"
@@ -147,6 +149,7 @@ const App = () => {
 ```
 
 </Step>
+
 <Step
   title="Sign Out"
   subtitle="1 step"
@@ -176,6 +179,7 @@ export default SignOutButton;
 ```
 
 </Step>
+
 <Step
   title="Further Readings"
   subtitle="3 steps"
diff --git a/packages/console/src/assets/docs/tutorial/integrate-sdk/react_zh-cn.mdx b/packages/console/src/assets/docs/tutorial/integrate-sdk/react_zh-cn.mdx
index 647e7fb01..1ebf5d3cf 100644
--- a/packages/console/src/assets/docs/tutorial/integrate-sdk/react_zh-cn.mdx
+++ b/packages/console/src/assets/docs/tutorial/integrate-sdk/react_zh-cn.mdx
@@ -50,6 +50,7 @@ pnpm build
 </TabItem>
 </Tabs>
 </Step>
+
 <Step
   title="Initiate LogtoClient"
   subtitle="1 step"
@@ -96,6 +97,7 @@ const App = () => {
 ```
 
 </Step>
+
 <Step
   title="Sign In"
   subtitle="2 steps"
@@ -148,6 +150,7 @@ const App = () => {
 ```
 
 </Step>
+
 <Step
   title="Sign Out"
   subtitle="1 step"
@@ -177,6 +180,7 @@ export default SignOutButton;
 ```
 
 </Step>
+
 <Step
   title="Further Readings"
   subtitle="3 steps"
diff --git a/packages/docs/docs/tutorial/integrate-sdk/react.mdx b/packages/docs/docs/tutorial/integrate-sdk/react.mdx
index e9bbb40f6..87f3c60ba 100644
--- a/packages/docs/docs/tutorial/integrate-sdk/react.mdx
+++ b/packages/docs/docs/tutorial/integrate-sdk/react.mdx
@@ -69,7 +69,7 @@ const App = () => (
 
 :::tip
 
-In the following code snippets, we assume the application runs in `http://localhost:1234`.
+In the following code snippets, we assume the application runs on `http://localhost:1234`.
 
 :::
 
@@ -85,10 +85,12 @@ First let's create a callback component:
 import { useHandleSignInCallback } from '@logto/react';
 
 const Callback = () => {
-  useHandleSignInCallback();
+  const { isLoading } = useHandleSignInCallback();
 
   // When it's working in progress
-  return <>Loading...</>;
+  if (isLoading) {
+    return <div>Redirecting...</div>;
+  }
 };
 ```
 
@@ -133,7 +135,7 @@ const Component = () => {
 
 ## Sign Out
 
-Calling `.signOut()` will clean all the Logto data in memory and LocalStorage, if it has.
+Calling `.signOut()` will clear all the Logto data in memory and localStorage, if they exist.
 
 To make the user come back to your application after signing out,
 it's necessary to add `http://localhost:1234` as one of the Post Sign Out URIs and use the URL as the parameter when calling `.signOut()`.
diff --git a/packages/docs/docs/tutorial/integrate-sdk/vue.mdx b/packages/docs/docs/tutorial/integrate-sdk/vue.mdx
index 5e5a41459..213162d90 100644
--- a/packages/docs/docs/tutorial/integrate-sdk/vue.mdx
+++ b/packages/docs/docs/tutorial/integrate-sdk/vue.mdx
@@ -145,7 +145,7 @@ const { isAuthenticated } = useLogto();
 
 ## Sign Out
 
-Calling `.signOut()` will clear all the Logto data in memory and LocalStorage, if there is any.
+Calling `.signOut()` will clear all the Logto data in memory and LocalStorage, if they exist.
 
 To make the user come back to your application after signing out,
 it's necessary to add `http://localhost:1234` as one of the Post Sign Out URIs and use the URL as the parameter when calling `.signOut()`.
diff --git a/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/react.mdx b/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/react.mdx
index e085b0b3e..cd64d60e8 100644
--- a/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/react.mdx
+++ b/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/react.mdx
@@ -1,16 +1,19 @@
+---
+sidebar_label: React
+---
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
+import AppNote from './components/AppNote';
+import SignInNote from './components/SignInNote';
+
 # 集成 `@logto/react`
 
-<Step
-  title="安装 SDK"
-  subtitle="选择您熟悉的安装方式"
-  index={0}
-  activeIndex={props.activeStepIndex}
-  invalidIndex={props.invalidStepIndex}
-  onNext={() => props.onNext(1)}
->
+<AppNote type="Single Page" />
+
+## 安装 SDK
+
 <Tabs>
 <TabItem value="npm" label="npm">
 
@@ -35,156 +38,118 @@ pnpm add @logto/react
 </TabItem>
 <TabItem value="script" label="script">
 
+{/* This should be CDN URL */}
 ```html
 <script src="https://logto.io/js/logto-sdk-react/0.1.0/logto-sdk-react.production.js" />
 ```
 
-</TabItem>
-<TabItem value="git" label="Git">
-
-```bash
-git clone https://github.com/logto-io/js.git
-pnpm build
-```
-
 </TabItem>
 </Tabs>
-</Step>
-<Step
-  title="Initiate LogtoClient"
-  subtitle="1 step"
-  index={1}
-  activeIndex={props.activeStepIndex}
-  invalidIndex={props.invalidStepIndex}
-  onNext={() => props.onNext(2)}
->
 
-在项目的 html 文件中，加入如下代码（需提前准备好 client ID 以及 authorization domain）
-Add the following code to your main html file. You may need client ID and authorization domain.
+## 初始化 LogtoClient
 
-```typescript
+Import 并使用 `LogtoProvider` 来提供 Logto context:
+
+```tsx
 import { LogtoProvider, LogtoConfig } from '@logto/react';
-import React from 'react';
 
-//...
-
-const App = () => {
-  const config: LogtoConfig = { clientId: 'foo', endpoint: 'https://your-endpoint-domain.com' };
-
-  return (
-    <BrowserRouter>
-      <LogtoProvider config={config}>
-        <Routes>
-          <Route path="/" element={<Home />} />
-          <Route path="/callback" element={<Callback />} />
-          <Route
-            path="/protected-resource"
-            element={
-              <RequireAuth>
-                <ProtectedResource />
-              </RequireAuth>
-            }
-          />
-        </Routes>
-      </LogtoProvider>
-    </BrowserRouter>
-  );
-};
-```
-
-</Step>
-<Step
-  title="Sign In"
-  subtitle="2 steps"
-  index={2}
-  activeIndex={props.activeStepIndex}
-  invalidIndex={props.invalidStepIndex}
-  onNext={() => props.onNext(3)}
->
-
-### Setup your login
-
-The Logto React SDK provides you tools and hooks to quickly implement your own authorization flow. First, let’s enter your redirect URI
-
-<MultiTextInputField name="redirectUris" title="Redirect URI" onError={() => props.onError(2)} />
-
-Add the following code to your web app
-
-```typescript
-import React from 'react';
-import { useLogto } from '@logto/react';
-
-const SignInButton = () => {
-  const { signIn } = useLogto();
-  const redirectUrl = window.location.origin + '/callback';
-
-  return <button onClick={() => signIn(redirectUrl)}>Sign In</button>;
+const config: LogtoConfig = {
+  appId: '<your-application-id>',
+  endpoint: '<your-logto-endpoint>'
 };
 
-export default SignInButton;
+const App = () => (
+  <LogtoProvider config={config}>
+    {/* Your app content */}
+  </LogtoProvider>
+);
 ```
 
-### Retrieve Auth Status
+## 登录
 
-```typescript
-import React from "react";
-import { useLogto } from '@logto/react';
+:::tip
 
-const App = () => {
-	const { isAuthenticated, signIn } = useLogto();
+在如下代码示例中, 我们均先假设你的 React 应用运行在 `http://localhost:1234` 上。
 
-  if !(isAuthenticated) {
-		return <SignInButton />
+:::
+
+我们提供了两个 hook 方法 `useHandleSignInCallback()` 和 `useLogto()`，它们可以帮助你轻松完成登录认证流程。
+
+### 设置回调路由
+
+为了让登录认证流程能够正常工作，我们需要设置一个回调路由，以便在认证结束后跳转回你的应用时它能够处理认证结果。（请注意：此路由地址不能受登录保护）
+
+首先，让我们来创建一个 Callback 组件：
+
+```tsx
+import { useHandleSignInCallback } from '@logto/react';
+
+const Callback = () => {
+  const { isLoading } = useHandleSignInCallback();
+
+  // 当登录认证尚未完成时
+  if (isLoading) {
+    return <div>页面跳转中...</div>;
   }
-
-	return <>
-		<AppContent />
-		<SignOutButton />
-	</>
 };
 ```
 
-</Step>
-<Step
-  title="Sign Out"
-  subtitle="1 step"
-  index={3}
-  activeIndex={props.activeStepIndex}
-  invalidIndex={props.invalidStepIndex}
-  onNext={() => props.onNext(4)}
->
+然后我们可以在路由表中添加这个回调路由。假设我们的路由地址定义为 `/callback`，且使用的路由工具为 `react-router`：
 
-Execute signOut() methods will redirect users to the Logto sign out page. After a success sign out, all use session data and auth status will be cleared.
+```tsx
+const Component = () => (
+  <Route path="/callback" element={<Callback />} />
+);
+```
 
-<MultiTextInputField name="postLogoutRedirectUris" title="Post sign out redirect URI" onError={() => props.onError(3)} />
+### 创建一个登录按钮
 
-Add the following code to your web app
+<SignInNote calling=".signIn()" />
 
-```typescript
-import React from 'react';
+```tsx
 import { useLogto } from '@logto/react';
 
-const SignOutButton = () => {
+const SignIn = () => {
+  const { signIn } = useLogto();
+
+  return <button onClick={() => signIn('http://localhost:1234/callback')}>登录</button>;
+};
+```
+
+### 判断当前登录状态
+
+```tsx
+import { useLogto } from '@logto/react';
+
+const Component = () => {
+  const { isAuthenticated } = useLogto();
+
+  if (!isAuthenticated) {
+    // 跳转到登录页面
+  }
+  
+  // 实现用户登录之后的业务逻辑
+};
+```
+
+## 登出
+
+调用 `.signOut()` 方法会清除所有在缓存或者 localStorage 中的 Logto 数据（如果有）。
+
+为了确保用户登出后能够跳转回你的应用，我们需要首先在管理界面中将 `http://localhost:1234` 添加到允许登出后跳转的地址列表（Post Sign Out URIs）中。
+
+```tsx
+import { useLogto } from '@logto/react';
+
+const SignOut = () => {
   const { signOut } = useLogto();
 
-  return <button onClick={() => signOut(window.location.origin)}>Sign out</button>;
+  return <button onClick={() => signOut('http://localhost:1234')}>登出</button>;
 };
-
-export default SignOutButton;
 ```
 
-</Step>
-<Step
-  title="Further Readings"
-  subtitle="3 steps"
-  index={4}
-  activeIndex={props.activeStepIndex}
-  invalidIndex={props.invalidStepIndex}
-  buttonHtmlType="submit"
->
+## Further Readings
 
 - [SDK Documentation](https://link-url-here.org)
 - [OIDC Documentation](https://link-url-here.org)
 - [Calling API to fetch accessToken](https://link-url-here.org)
-
-</Step>