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

---
 .../docs/tutorial/integrate-sdk/README.md     |   2 +-
 .../docs/docs/tutorial/integrate-sdk/vue.mdx  | 168 ++++++++++++++++++
 .../integrate-sdk/components/AppNote.tsx      |  16 ++
 .../integrate-sdk/components/SignInNote.tsx   |  16 ++
 .../current/tutorial/integrate-sdk/vue.mdx    | 167 +++++++++++++++++
 5 files changed, 368 insertions(+), 1 deletion(-)
 create mode 100644 packages/docs/docs/tutorial/integrate-sdk/vue.mdx
 create mode 100644 packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/components/AppNote.tsx
 create mode 100644 packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/components/SignInNote.tsx
 create mode 100644 packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/vue.mdx

diff --git a/packages/docs/docs/tutorial/integrate-sdk/README.md b/packages/docs/docs/tutorial/integrate-sdk/README.md
index 5820f817b..49d3d3be2 100644
--- a/packages/docs/docs/tutorial/integrate-sdk/README.md
+++ b/packages/docs/docs/tutorial/integrate-sdk/README.md
@@ -8,7 +8,7 @@ If the list doesn't cover your desired platform/framework, please file a feature
 
 - Vanilla JS
 - [React](./react)
-- Vue
+- [Vue](./vue)
 
 ## Native
 
diff --git a/packages/docs/docs/tutorial/integrate-sdk/vue.mdx b/packages/docs/docs/tutorial/integrate-sdk/vue.mdx
new file mode 100644
index 000000000..5e5a41459
--- /dev/null
+++ b/packages/docs/docs/tutorial/integrate-sdk/vue.mdx
@@ -0,0 +1,168 @@
+---
+sidebar_label: Vue
+---
+
+import Admonition from '@theme/Admonition';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+import AppNote from './components/AppNote';
+import SignInNote from './components/SignInNote';
+
+# Integrate `@logto/vue`
+
+<AppNote type="Single Page" />
+
+## Import SDK
+
+<Tabs>
+<TabItem value="npm" label="npm">
+
+```bash
+npm i @logto/vue
+```
+
+</TabItem>
+<TabItem value="yarn" label="Yarn">
+
+```bash
+yarn add @logto/vue
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash
+pnpm add @logto/vue
+```
+
+</TabItem>
+<TabItem value="script" label="script">
+
+{/* This should be CDN URL */}
+```html
+<script src="https://logto.io/js/logto-sdk-vue/0.1.0/logto-sdk-vue.production.js" />
+```
+
+</TabItem>
+</Tabs>
+
+<Admonition type="note">
+  We only support Vue 3 Composition API at this point. Will add support to Vue Options API and possibly Vue 2 in future releases.
+</Admonition>
+
+## Init LogtoClient
+
+Import and use `createLogto` to install Logto plugin:
+
+```ts
+import { createLogto, LogtoConfig } from '@logto/vue';
+
+const config: LogtoConfig = {
+  appId: '<your-application-id>',
+  endpoint: '<your-logto-endpoint>'
+};
+
+const app = createApp(App);
+
+app.use(createLogto, config);
+app.mount("#app");
+```
+
+## Sign In
+
+:::tip
+
+In the following code snippets, we assume the application runs on `http://localhost:1234`.
+
+:::
+
+We provide two composables `useHandleSignInCallback()` and `useLogto()` which can help you easily manage the authentication flow. 
+
+### Set Up Callback Route
+
+In order to handle what comes from Logto, the application needs to have a dedicated callback route that does NOT require authentication.
+
+First let's create a callback component:
+
+```html
+<script setup lang="ts">
+  import { useHandleSignInCallback } from "@logto/vue";
+  const { isLoading } = useHandleSignInCallback();
+</script>
+
+<template>
+  <!-- When it's working in progress -->
+  <p v-if="isLoading">Redirecting...</p>
+</template>
+```
+
+Then we need to link the callback component with the route. Let's say the path is `/callback` and we are using `vue-router`:
+
+```ts
+const router = createRouter({
+  routes: [
+    {
+      path: "/callback",
+      name: "callback",
+      component: CallbackView,
+    },
+  ]
+});
+```
+
+### Make a Sign In Button
+
+<SignInNote calling=".signIn()" />
+
+```ts
+import { useLogto } from "@logto/vue";
+
+const { signIn } = useLogto();
+const onClickSignIn = () => signIn(redirectUrl);
+```
+
+```html
+<button @click="onClickSignIn">Sign In</button>
+```
+
+### Retrieve Authentication Status
+
+```ts
+import { useLogto } from '@logto/vue';
+
+const { isAuthenticated } = useLogto();
+```
+
+```html
+<div v-if="!isAuthenticated">
+  <!-- E.g. navigate to the sign in page -->
+</div>
+<div v-else>
+  <!-- Do things when user is authenticated -->
+</div>
+```
+
+## Sign Out
+
+Calling `.signOut()` will clear all the Logto data in memory and LocalStorage, if there is any.
+
+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()`.
+
+```ts
+import { useLogto } from "@logto/vue";
+
+const { signOut } = useLogto();
+const onClickSignOut = () => signOut('http://localhost:1234');
+```
+
+```html
+<button @click="onClickSignOut">Sign Out</button>
+```
+
+## 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)
diff --git a/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/components/AppNote.tsx b/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/components/AppNote.tsx
new file mode 100644
index 000000000..9ff1dc648
--- /dev/null
+++ b/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/components/AppNote.tsx
@@ -0,0 +1,16 @@
+import React, { ReactNode } from 'react'
+import Admonition from '@theme/Admonition';
+
+type Props = {
+  type: ReactNode;
+};
+
+const AppNote = ({ type }: Props) => {
+  return (
+    <Admonition type="note">
+      本篇教程默认你已经在管理界面中成功创建了一个 {type} 应用。如果你还没有完成这一步操作，请参阅这篇教程，创建应用之后再继续。
+    </Admonition>
+  );
+};
+
+export default AppNote
diff --git a/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/components/SignInNote.tsx b/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/components/SignInNote.tsx
new file mode 100644
index 000000000..ad10fb012
--- /dev/null
+++ b/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/components/SignInNote.tsx
@@ -0,0 +1,16 @@
+import React, { ReactNode } from 'react';
+import Admonition from '@theme/Admonition';
+
+type Props = {
+  calling: ReactNode;
+};
+
+const SignInNote = ({ calling }: Props) => {
+  return (
+    <Admonition type="note">
+      在调用 <code>{calling}</code> 之前，请首先确保已经在管理界面中正确 <a href="https://logto.io">配置 Redirect URI</a>
+    </Admonition>
+  );
+};
+
+export default SignInNote;
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
new file mode 100644
index 000000000..8a0a3df26
--- /dev/null
+++ b/packages/docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/integrate-sdk/vue.mdx
@@ -0,0 +1,167 @@
+---
+sidebar_label: Vue
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+import AppNote from './components/AppNote';
+import SignInNote from './components/SignInNote';
+
+# 集成 `@logto/vue`
+
+<AppNote type="Single Page" />
+
+## 安装 SDK
+
+<Tabs>
+<TabItem value="npm" label="npm">
+
+```bash
+npm i @logto/vue
+```
+
+</TabItem>
+<TabItem value="yarn" label="Yarn">
+
+```bash
+yarn add @logto/vue
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash
+pnpm add @logto/vue
+```
+
+</TabItem>
+<TabItem value="script" label="script">
+
+{/* This should be CDN URL */}
+```html
+<script src="https://logto.io/js/logto-sdk-vue/0.1.0/logto-sdk-vue.production.js" />
+```
+
+</TabItem>
+</Tabs>
+
+<Admonition type="note">
+  目前仅支持 Vue 3 的 组合式（Composition）API，我们会在后续版本中陆续添加对选项式（Options）API 和 Vue 2 的支持。
+</Admonition>
+
+## 初始化 LogtoClient
+
+Import 并使用 `createLogto` 以插件的形式安装 Logto:
+
+```ts
+import { createLogto, LogtoConfig } from '@logto/vue';
+
+const config: LogtoConfig = {
+  appId: '<your-application-id>',
+  endpoint: '<your-logto-endpoint>'
+};
+
+const app = createApp(App);
+
+app.use(createLogto, config);
+app.mount("#app");
+```
+
+## 登录
+
+:::tip
+
+在如下代码示例中, 我们均先假设你的 Vue 应用运行在 `http://localhost:1234` 上。
+
+:::
+
+我们提供了两个组合式 API `useHandleSignInCallback()` 和 `useLogto()`，它们可以帮助你轻松完成登录认证流程。 
+
+### 设置回调路由
+
+为了让登录认证流程能够正常工作，我们需要设置一个回调路由，以便在认证结束后跳转回你的应用时它能够处理认证结果。（请注意：此路由地址不能受登录保护）
+
+首先，让我们来创建一个 CallbackView 组件：
+
+```html
+<script setup lang="ts">
+  import { useHandleSignInCallback } from "@logto/vue";
+  const { isLoading } = useHandleSignInCallback();
+</script>
+
+<template>
+  <!-- 当登录认证尚未完成时 -->
+  <p v-if="isLoading">页面跳转中...</p>
+</template>
+```
+
+然后我们可以在路由表中添加这个回调路由。假设我们的路由地址定义为 `/callback`，且使用的路由工具为 `vue-router`:
+
+```ts
+const router = createRouter({
+  ...
+  routes: [
+    {
+      path: "/callback",
+      name: "callback",
+      component: CallbackView,
+    },
+  ]
+});
+```
+
+### 创建一个登录按钮
+
+<SignInNote calling=".signIn()" />
+
+```ts
+import { useLogto } from "@logto/vue";
+
+const { signIn } = useLogto();
+const onClickSignIn = () => signIn(redirectUrl);
+```
+
+```html
+<button @click="onClickSignIn">登录</button>
+```
+
+### 判断当前登录状态
+
+```ts
+import { useLogto } from '@logto/vue';
+
+const { isAuthenticated } = useLogto();
+```
+
+```html
+<div v-if="!isAuthenticated">
+  <!-- 跳转到登录页面 -->
+</div>
+<div v-else>
+  <!-- 实现用户登录之后的业务逻辑 -->
+</div>
+```
+
+## 登出
+
+调用 `.signOut()` 方法会清除所有在缓存或者 localStorage 中的 Logto 数据（如果有）。
+
+为了确保用户登出后能够跳转回你的应用，我们需要首先在管理界面中将 `http://localhost:1234` 添加到允许登出后跳转的地址列表（Post Sign Out URIs）中。
+
+```ts
+import { useLogto } from "@logto/vue";
+
+const { signOut } = useLogto();
+const onClickSignOut = () => signOut('http://localhost:1234');
+```
+
+```html
+<button @click="onClickSignOut">登出</button>
+```
+
+## 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)