@arcblock/did-connect-react 3.1.40 → 3.1.42

package/docs/hooks-use-oauth-passkey.zh.md

@@ -0,0 +1,188 @@
+# useOAuth & usePasskey
+
+`DidConnect` 组件和 `useConnect` hook 为所有身份验证方法提供了全面的、预构建的用户界面，但你可能需要构建自定义的身份验证流程。`useOAuth` 和 `usePasskey` hook 提供了对社交登录 (OAuth) 和无密码身份验证 (Passkey) 底层逻辑的直接访问。
+
+这些 hook 是创建定制化用户体验的强大工具。它们依赖于各自的上下文提供程序 `OAuthProvider` 和 `PasskeyProvider`，这些提供程序通常包含在主 `SessionProvider` 中。有关会话管理的更多信息，请参阅 [SessionProvider 文档](./core-components-session-provider.md)。
+
+## useOAuth
+
+`useOAuth` hook 提供了用于处理第三方社交登录流程的函数和状态。
+
+### 导入
+
+```javascript icon=logos:javascript
+import { useOAuth } from '@arcblock/did-connect-react/lib/OAuth';
+```
+
+### 返回值
+
+该 hook 返回一个包含以下属性和方法的对象：
+
+<x-field-group>
+  <x-field data-name="loginOAuth" data-type="function" data-required="true">
+    <x-field-desc markdown>使用指定的 OAuth 提供商启动登录流程。它会打开一个弹出窗口供用户授权，并返回一个解析为登录结果的 promise。</x-field-desc>
+  </x-field>
+  <x-field data-name="bindOAuth" data-type="function" data-required="true">
+    <x-field-desc markdown>将新的 OAuth 帐户绑定到当前登录用户的会话。</x-field-desc>
+  </x-field>
+  <x-field data-name="unbindOAuth" data-type="function" data-required="true">
+    <x-field-desc markdown>从当前用户的会话中解绑 OAuth 帐户。</x-field-desc>
+  </x-field>
+  <x-field data-name="getOAuthConfigList" data-type="function" data-required="true">
+    <x-field-desc markdown>从 Blocklet 设置中获取已启用和已配置的 OAuth 提供商列表。返回一个解析为提供商配置对象数组的 promise。</x-field-desc>
+  </x-field>
+  <x-field data-name="switchOAuthPassport" data-type="function" data-required="true">
+    <x-field-desc markdown>启动一个流程，用于在同一身份的不同已连接帐户（通行证）之间切换。</x-field-desc>
+  </x-field>
+  <x-field data-name="bindAuthLoading" data-type="boolean" data-required="true">
+    <x-field-desc markdown>一个布尔标志，当 `bindOAuth` 操作正在进行时为 `true`。</x-field-desc>
+  </x-field>
+  <x-field data-name="unbindAuthLoading" data-type="boolean" data-required="true">
+    <x-field-desc markdown>一个布尔标志，当 `unbindOAuth` 操作正在进行时为 `true`。</x-field-desc>
+  </x-field>
+  <x-field data-name="oauthState" data-type="object" data-required="true">
+    <x-field-desc markdown>一个包含身份验证过程实时状态的对象。</x-field-desc>
+    <x-field data-name="loading" data-type="boolean" data-desc="如果 OAuth 操作正在进行，则为 True。"></x-field>
+    <x-field data-name="error" data-type="string" data-desc="如果操作失败，则包含错误消息。"></x-field>
+    <x-field data-name="status" data-type="string" data-desc="流程的当前状态（例如，'scanned', 'succeed', 'error'）。"></x-field>
+  </x-field>
+</x-field-group>
+
+### 用法示例
+
+以下是如何构建自定义社交登录组件的示例。
+
+```jsx CustomSocialLogin.jsx icon=logos:react
+import React, { useEffect, useState } from 'react';
+import { useOAuth } from '@arcblock/did-connect-react/lib/OAuth';
+import { useSession } from '@arcblock/did-connect-react/lib/Session';
+
+export default function CustomSocialLogin() {
+  const { loginOAuth, getOAuthConfigList } = useOAuth();
+  const { session } = useSession();
+  const [providers, setProviders] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    // 组件挂载时获取可用的 OAuth 提供商列表
+    getOAuthConfigList().then(setProviders).catch(console.error);
+  }, [getOAuthConfigList]);
+
+  const handleLogin = async (provider) => {
+    setLoading(true);
+    setError('');
+    try {
+      const result = await loginOAuth({ provider: provider.provider });
+      // 成功登录后，会话将由 SessionProvider 自动更新。
+      console.log('Login successful:', result);
+      // 你可能需要在此处刷新会话或重定向用户。
+    } catch (err) {
+      setError(err.message);
+      console.error('Login failed:', err);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (session.user) {
+    return <div>您已登录为 {session.user.name}。</div>;
+  }
+
+  if (providers.length === 0) {
+    return <div>未配置社交登录方法。</div>;
+  }
+
+  return (
+    <div>
+      <h3>使用社交媒体登录</h3>
+      {providers.map((p) => (
+        <button key={p.provider} onClick={() => handleLogin(p)} disabled={loading}>
+          {loading ? '登录中...' : `使用 ${p.provider} 登录`}
+        </button>
+      ))}
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+    </div>
+  );
+}
+```
+
+## usePasskey
+
+`usePasskey` hook 提供了使用 WebAuthn (Passkeys) 处理无密码身份验证的函数和状态。
+
+### 导入
+
+```javascript icon=logos:javascript
+import { usePasskey } from '@arcblock/did-connect-react/lib/Passkey';
+```
+
+### 返回值
+
+该 hook 返回一个包含以下属性和方法的对象：
+
+<x-field-group>
+  <x-field data-name="loginPasskey" data-type="function" data-required="true">
+    <x-field-desc markdown>使用现有的 Passkey 启动登录流程。它会触发浏览器的原生 WebAuthn 身份验证提示。</x-field-desc>
+  </x-field>
+  <x-field data-name="connectPasskey" data-type="function" data-required="true">
+    <x-field-desc markdown>启动一个流程，以创建新的 Passkey 并将其绑定到当前用户的会话。</x-field-desc>
+  </x-field>
+  <x-field data-name="disconnectPasskey" data-type="function" data-required="true">
+    <x-field-desc markdown>成功验证后，从当前用户的会话中解绑 Passkey。</x-field-desc>
+  </x-field>
+  <x-field data-name="switchPassport" data-type="function" data-required="true">
+    <x-field-desc markdown>启动一个流程，用于在不同的已连接帐户（通行证）之间切换。</x-field-desc>
+  </x-field>
+  <x-field data-name="connecting" data-type="boolean" data-required="true">
+    <x-field-desc markdown>一个布尔标志，当 `connectPasskey` 操作正在进行时为 `true`。</x-field-desc>
+  </x-field>
+  <x-field data-name="disconnecting" data-type="boolean" data-required="true">
+    <x-field-desc markdown>一个布尔标志，当 `disconnectPasskey` 操作正在进行时为 `true`。</x-field-desc>
+  </x-field>
+  <x-field data-name="passkeyState" data-type="object" data-required="true">
+    <x-field-desc markdown>一个包含 Passkey 操作实时状态的对象。</x-field-desc>
+    <x-field data-name="loading" data-type="boolean" data-desc="如果 Passkey 操作正在进行，则为 True。"></x-field>
+    <x-field data-name="creating" data-type="boolean" data-desc="在 Passkey 创建阶段为 True。"></x-field>
+    <x-field data-name="verifying" data-type="boolean" data-desc="在 Passkey 验证阶段为 True。"></x-field>
+    <x-field data-name="error" data-type="string" data-desc="如果操作失败，则包含错误消息。"></x-field>
+    <x-field data-name="status" data-type="string" data-desc="流程的当前状态（例如，'scanned', 'succeed', 'error'）。"></x-field>
+  </x-field>
+</x-field-group>
+
+### 用法示例
+
+以下是如何创建“使用 Passkey 登录”按钮的示例。
+
+```jsx PasskeyLoginButton.jsx icon=logos:react
+import React, { useState } from 'react';
+import { usePasskey } from '@arcblock/did-connect-react/lib/Passkey';
+
+export default function PasskeyLoginButton() {
+  const { loginPasskey, passkeyState } = usePasskey();
+  const [error, setError] = useState('');
+
+  const handleLogin = async () => {
+    setError('');
+    try {
+      const result = await loginPasskey();
+      console.log('Passkey login successful:', result);
+      // 会话将由 SessionProvider 自动更新。
+    } catch (err) {
+      setError(err.message);
+      console.error('Passkey login failed:', err);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleLogin} disabled={passkeyState.loading}>
+        {passkeyState.loading ? '验证中...' : '使用 Passkey 登录'}
+      </button>
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+    </div>
+  );
+}
+```
+
+这些 hook 提供了将 DID Connect 强大的身份验证功能以完全自定义的 UI 集成到应用程序任何部分的灵活性。要了解如何以编程方式控制预构建的 `DidConnect` 模态框，请继续阅读 [useConnect hook 文档](./hooks-use-connect.md)。

package/docs/hooks.ja.md

@@ -0,0 +1,23 @@
+# フック
+
+`@arcblock/did-connect-react` ライブラリは、プログラムによる制御と柔軟なデータアクセスを提供する強力なReactフックのセットを提供します。[SessionProvider](./core-components-session-provider.md) は便利なコンテキストベースのアプローチを提供しますが、フックは複雑なUIや高度なユースケースに必要なきめ細かい制御を提供します。
+
+これらのフックを使用すると、接続フローの管理、ユーザーデータへのアクセス、および `SessionProvider` のスコープ内の任意のコンポーネントからさまざまな認証方法を統合できます。
+
+<x-cards data-columns="3">
+  <x-card data-title="useConnect" data-icon="lucide:plug-zap" data-href="/hooks/use-connect">
+    DID Connect UIモーダルをプログラムで開閉・管理します。これは接続フローを制御するためのコアフックです。
+  </x-card>
+  <x-card data-title="useDid" data-icon="lucide:user-check" data-href="/hooks/use-did">
+    セッションから認証されたユーザーのDID、プロフィール、ウォレット情報に簡単にアクセスして作業するための便利なユーティリティフックです。
+  </x-card>
+  <x-card data-title="useOAuth & usePasskey" data-icon="lucide:key-round" data-href="/hooks/use-oauth-passkey">
+    モダンで代替的な認証方法を統合します。`useOAuth` はソーシャルログインを処理し、`usePasskey` は安全なパスワードレス認証を可能にします。
+  </x-card>
+</x-cards>
+
+## 概要
+
+これらのフックを活用することで、高度にカスタマイズされたシームレスなユーザーエクスペリエンスを構築できます。まず `useConnect` を調べてログインフローをトリガーする方法を理解し、次に `useDid` がユーザー情報を表示するのにどのように役立つかを確認してください。
+
+さらに深く掘り下げますか？上記のフックから選択して詳細を学ぶか、[UIコンポーネント](./ui-components.md)セクションに進んでユーザーデータの表示方法を確認してください。

package/docs/hooks.md

@@ -0,0 +1,23 @@
+# Hooks
+
+The `@arcblock/did-connect-react` library offers a powerful set of React hooks that provide programmatic control and flexible data access. While the [SessionProvider](./core-components-session-provider.md) offers a convenient context-based approach, hooks give you the fine-grained control needed for complex UIs and advanced use cases.
+
+These hooks allow you to manage the connection flow, access user data, and integrate various authentication methods from any component within the `SessionProvider`'s scope.
+
+<x-cards data-columns="3">
+  <x-card data-title="useConnect" data-icon="lucide:plug-zap" data-href="/hooks/use-connect">
+    Programmatically open, close, and manage the DID Connect UI modal. This is the core hook for controlling the connection flow.
+  </x-card>
+  <x-card data-title="useDid" data-icon="lucide:user-check" data-href="/hooks/use-did">
+    A convenient utility hook to easily access and work with the authenticated user's DID, profile, and wallet information from the session.
+  </x-card>
+  <x-card data-title="useOAuth & usePasskey" data-icon="lucide:key-round" data-href="/hooks/use-oauth-passkey">
+    Integrate modern, alternative authentication methods. `useOAuth` handles social logins, while `usePasskey` enables secure, passwordless authentication.
+  </x-card>
+</x-cards>
+
+## Summary
+
+By leveraging these hooks, you can build highly customized and seamless user experiences. Start by exploring `useConnect` to understand how to trigger the login flow, then see how `useDid` can help you display user information.
+
+Ready to dive deeper? Choose a hook from above to learn more, or proceed to the [UI Components](./ui-components.md) section to see how you can display user data.

package/docs/hooks.zh-TW.md

@@ -0,0 +1,23 @@
+# Hooks
+
+`@arcblock/did-connect-react` 函式庫提供了一組強大的 React hooks，可提供程式化控制和靈活的資料存取。雖然 [SessionProvider](./core-components-session-provider.md) 提供了一種方便的基於上下文的方法，但 hooks 為您提供了複雜 UI 和進階用例所需的精細控制。
+
+這些 hooks 讓您可以在 `SessionProvider` 作用域內的任何元件中管理連接流程、存取使用者資料以及整合各種身份驗證方法。
+
+<x-cards data-columns="3">
+  <x-card data-title="useConnect" data-icon="lucide:plug-zap" data-href="/hooks/use-connect">
+    以程式化方式開啟、關閉和管理 DID Connect UI 互動視窗。這是控制連接流程的核心 hook。
+  </x-card>
+  <x-card data-title="useDid" data-icon="lucide:user-check" data-href="/hooks/use-did">
+    一個方便的實用工具 hook，可輕鬆從 session 中存取和使用通過身份驗證的使用者的 DID、個人資料和錢包資訊。
+  </x-card>
+  <x-card data-title="useOAuth & usePasskey" data-icon="lucide:key-round" data-href="/hooks/use-oauth-passkey">
+    整合現代的替代身份驗證方法。`useOAuth` 處理社交登入，而 `usePasskey` 則啟用安全、無密碼的身份驗證。
+  </x-card>
+</x-cards>
+
+## 總結
+
+透過利用這些 hooks，您可以建構高度客製化和無縫的使用者體驗。首先探索 `useConnect` 以了解如何觸發登入流程，然後看看 `useDid` 如何幫助您顯示使用者資訊。
+
+準備好深入了解了嗎？從上面選擇一個 hook 以了解更多資訊，或前往 [UI Components](./ui-components.md) 部分查看如何顯示使用者資料。

package/docs/hooks.zh.md

@@ -0,0 +1,23 @@
+# Hooks
+
+`@arcblock/did-connect-react` 库提供了一套功能强大的 React Hooks，可实现编程控制和灵活的数据访问。虽然 [SessionProvider](./core-components-session-provider.md) 提供了一种方便的基于上下文的方法，但 Hooks 为您提供了复杂 UI 和高级用例所需的精细控制。
+
+这些 Hooks 允许您从 `SessionProvider` 作用域内的任何组件管理连接流程、访问用户数据并集成各种身份验证方法。
+
+<x-cards data-columns="3">
+  <x-card data-title="useConnect" data-icon="lucide:plug-zap" data-href="/hooks/use-connect">
+    以编程方式打开、关闭和管理 DID Connect UI 模态框。这是控制连接流程的核心 Hook。
+  </x-card>
+  <x-card data-title="useDid" data-icon="lucide:user-check" data-href="/hooks/use-did">
+    一个方便的实用工具 Hook，可轻松访问和使用会话中经过身份验证的用户的 DID、个人资料和钱包信息。
+  </x-card>
+  <x-card data-title="useOAuth & usePasskey" data-icon="lucide:key-round" data-href="/hooks/use-oauth-passkey">
+    集成现代的替代身份验证方法。`useOAuth` 处理社交登录，而 `usePasskey` 则实现安全的无密码身份验证。
+  </x-card>
+</x-cards>
+
+## 摘要
+
+通过利用这些 Hooks，您可以构建高度定制化和无缝的用户体验。首先探索 `useConnect` 以了解如何触发登录流程，然后看看 `useDid` 如何帮助您显示用户信息。
+
+准备好深入了解了吗？从上面选择一个 Hook 以了解更多信息，或继续前往 [UI 组件](./ui-components.md) 部分查看如何显示用户数据。

package/docs/overview.ja.md

@@ -0,0 +1,159 @@
+# 概要
+
+`@arcblock/did-connect-react` ライブラリは、Webアプリケーションに分散型ID（DID）機能をシームレスに統合するために設計された、包括的なReactコンポーネントとフックのセットを提供します。ArcBlockのDID Walletを使用したユーザー認証とセッション管理のプロセスを簡素化し、従来のログインシステムに代わる安全でユーザーフレンドリーな代替手段を提供します。
+
+このライブラリは、完全なすぐに使えるソリューションが必要な場合でも、認証フローを詳細に制御する必要がある場合でも、柔軟で使いやすいように構築されています。
+
+### 主な機能
+
+<x-cards data-columns="2">
+  <x-card data-title="完全な接続UI" data-icon="lucide:qr-code-icon">
+    QRコードのスキャンと接続プロセス全体を処理するための、事前に構築されたカスタマイズ可能なモーダルである `DidConnect` コンポーネントが含まれています。
+  </x-card>
+  <x-card data-title="シームレスなセッション管理" data-icon="lucide:key-round">
+    `SessionProvider` と `useSession` フックを活用して、アプリケーション全体でユーザーのログイン状態、セッション、プロファイルデータを簡単に管理します。
+  </x-card>
+  <x-card data-title="柔軟なプログラム制御" data-icon="lucide:webhook">
+    `useConnect` のようなフックを使用して、接続モーダルをプログラムで開閉・管理し、ユーザーエクスペリエンスを完全に制御できます。
+  </x-card>
+  <x-card data-title="豊富なUIツールキット" data-icon="lucide:gem">
+    `Avatar`、`Address`、`Button` のような補足的なUIコンポーネントのコレクションで、ユーザーのID情報を一貫して表示します。
+  </x-card>
+</x-cards>
+
+### コアアーキテクチャ
+
+このライブラリは、ユーザーのセッション状態を管理する中央の `SessionProvider` を中心に展開します。`Button` のようなUIコンポーネントは `DidConnect` モーダルをトリガーし、ユーザーのDID Walletとの安全なQRコードベースの対話を処理します。接続が完了すると、セッションが更新され、アプリケーションのUIがそれに応じて反応します。
+
+```d2 Basic Authentication Flow
+direction: down
+
+User: { 
+  shape: c4-person 
+}
+
+Your-Application: {
+  label: "あなたのReactアプリケーション"
+  shape: rectangle
+
+  SessionProvider: {
+    label: "SessionProvider\n(セッション状態を管理)"
+    shape: rectangle
+
+    App-Components: {
+      label: "あなたのアプリコンポーネント"
+      shape: rectangle
+
+      ConnectButton: {
+        label: "ConnectButton"
+        shape: rectangle
+      }
+    }
+
+    DidConnect-Modal: {
+      label: "DidConnectモーダル\n(QRコードフローを処理)"
+      shape: rectangle
+    }
+  }
+}
+
+DID-Wallet: {
+  label: "DID Wallet"
+  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
+}
+
+User -> Your-Application.SessionProvider.App-Components.ConnectButton: "1. ボタンをクリック"
+Your-Application.SessionProvider.App-Components.ConnectButton -> Your-Application.SessionProvider.DidConnect-Modal: "2. モーダルを開く"
+Your-Application.SessionProvider.DidConnect-Modal -> User: "3. QRコードを表示"
+User -> DID-Wallet: "4. スキャンして承認"
+DID-Wallet -> Your-Application.SessionProvider: "5. 接続を完了"
+Your-Application.SessionProvider -> Your-Application.SessionProvider.App-Components: "6. セッション状態を更新"
+
+```
+
+### インストール
+
+始めるには、`yarn` または `npm` を使用してプロジェクトにライブラリを追加します。
+
+```shell Installation icon=lucide:download
+# With yarn
+yarn add @arcblock/did-connect-react
+
+# With npm
+npm install @arcblock/did-connect-react
+```
+
+### 仕組み：クイックルック
+
+これは、ログインフローを設定する方法の最小限の例です。アプリケーションは `SessionProvider` でラップされ、`Button` を使用して `DidConnect` モーダルを切り替えます。
+
+```jsx App.js icon=logos:react
+import React from 'react';
+import axios from 'axios';
+import { SessionProvider, SessionConsumer } from '@arcblock/did-connect-react/lib/Session';
+import DidConnect from '@arcblock/did-connect-react/lib/Connect';
+import Button from '@arcblock/did-connect-react/lib/Button';
+
+const webWalletUrl = 'https://web.abtwallet.io/';
+
+function App() {
+  const [isConnectOpen, setConnectOpen] = React.useState(false);
+
+  const handleClose = () => setConnectOpen(false);
+  const handleSuccess = () => {
+    // ログイン成功後にリダイレクトまたはUIを更新
+    window.location.reload();
+  };
+
+  return (
+    <SessionProvider serviceHost="/">
+      <div className="main-content">
+        <SessionConsumer>
+          {({ session }) => {
+            if (session.loading) {
+              return <div>セッションを読み込み中...</div>;
+            }
+
+            return session.user ? (
+              <div>
+                <h2>ようこそ、{session.user.did}さん！</h2>
+                <button onClick={() => session.logout()}>ログアウト</button>
+              </div>
+            ) : (
+              <Button onClick={() => setConnectOpen(true)}>ウォレットに接続</Button>
+            );
+          }}
+        </SessionConsumer>
+      </div>
+
+      <DidConnect
+        popup
+        open={isConnectOpen}
+        action="login"
+        checkFn={axios.get}
+        onClose={handleClose}
+        onSuccess={handleSuccess}
+        messages={{
+          title: 'マイアプリにログイン',
+          scan: 'DID WalletでQRコードをスキャンしてください',
+          confirm: 'ウォレットでログインを確認してください',
+          success: '正常にサインインしました！',
+        }}
+        webWalletUrl={webWalletUrl}
+      />
+    </SessionProvider>
+  );
+}
+
+export default App;
+```
+
+この例は、わずか数個のコンポーネントでユーザーセッションを管理し、ログインプロセスをトリガーする方法を示しています。
+
+### 次のステップ
+
+ライブラリの基本的な理解が得られたので、さらに深く掘り下げる準備ができました。
+
+<x-card data-title="はじめに" data-href="/getting-started" data-icon="lucide:rocket" data-cta="ビルドを開始">
+  ステップバイステップのガイドに従って、DID Connectをゼロから独自のアプリケーションに統合します。
+</x-card>

package/docs/overview.md

@@ -0,0 +1,159 @@
+# Overview
+
+The `@arcblock/did-connect-react` library provides a comprehensive set of React components and hooks designed to seamlessly integrate decentralized identity (DID) capabilities into your web applications. It simplifies the process of user authentication and session management using ArcBlock's DID Wallet, offering a secure and user-friendly alternative to traditional login systems.
+
+This library is built to be flexible and easy to use, whether you need a complete out-of-the-box solution or granular control over the authentication flow.
+
+### Key Features
+
+<x-cards data-columns="2">
+  <x-card data-title="Complete Connection UI" data-icon="lucide:qr-code-icon">
+    Includes the `DidConnect` component, a pre-built, customizable modal for handling the entire QR code scanning and connection process.
+  </x-card>
+  <x-card data-title="Seamless Session Management" data-icon="lucide:key-round">
+    Leverage the `SessionProvider` and `useSession` hook to effortlessly manage user login states, sessions, and profile data throughout your application.
+  </x-card>
+  <x-card data-title="Flexible Programmatic Control" data-icon="lucide:webhook">
+    Use hooks like `useConnect` to programmatically open, close, and manage the connection modal, giving you full control over the user experience.
+  </x-card>
+  <x-card data-title="Rich UI Toolkit" data-icon="lucide:gem">
+    A collection of supplementary UI components like `Avatar`, `Address`, and `Button` to display user identity information consistently.
+  </x-card>
+</x-cards>
+
+### Core Architecture
+
+The library revolves around a central `SessionProvider` that manages the user's session state. UI components like `Button` can trigger the `DidConnect` modal, which handles the secure, QR-code-based interaction with the user's DID Wallet. Once the connection is complete, the session is updated, and your application's UI reacts accordingly.
+
+```d2 Basic Authentication Flow
+direction: down
+
+User: { 
+  shape: c4-person 
+}
+
+Your-Application: {
+  label: "Your React Application"
+  shape: rectangle
+
+  SessionProvider: {
+    label: "SessionProvider\n(Manages session state)"
+    shape: rectangle
+
+    App-Components: {
+      label: "Your App Components"
+      shape: rectangle
+
+      ConnectButton: {
+        label: "ConnectButton"
+        shape: rectangle
+      }
+    }
+
+    DidConnect-Modal: {
+      label: "DidConnect Modal\n(Handles QR code flow)"
+      shape: rectangle
+    }
+  }
+}
+
+DID-Wallet: {
+  label: "DID Wallet"
+  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
+}
+
+User -> Your-Application.SessionProvider.App-Components.ConnectButton: "1. Clicks button"
+Your-Application.SessionProvider.App-Components.ConnectButton -> Your-Application.SessionProvider.DidConnect-Modal: "2. Opens modal"
+Your-Application.SessionProvider.DidConnect-Modal -> User: "3. Displays QR code"
+User -> DID-Wallet: "4. Scans & approves"
+DID-Wallet -> Your-Application.SessionProvider: "5. Completes connection"
+Your-Application.SessionProvider -> Your-Application.SessionProvider.App-Components: "6. Updates session state"
+
+```
+
+### Installation
+
+To get started, add the library to your project using `yarn` or `npm`.
+
+```shell Installation icon=lucide:download
+# With yarn
+yarn add @arcblock/did-connect-react
+
+# With npm
+npm install @arcblock/did-connect-react
+```
+
+### How It Works: A Quick Look
+
+Here is a minimal example of how to set up a login flow. The application is wrapped in a `SessionProvider`, and a `Button` is used to toggle the `DidConnect` modal.
+
+```jsx App.js icon=logos:react
+import React from 'react';
+import axios from 'axios';
+import { SessionProvider, SessionConsumer } from '@arcblock/did-connect-react/lib/Session';
+import DidConnect from '@arcblock/did-connect-react/lib/Connect';
+import Button from '@arcblock/did-connect-react/lib/Button';
+
+const webWalletUrl = 'https://web.abtwallet.io/';
+
+function App() {
+  const [isConnectOpen, setConnectOpen] = React.useState(false);
+
+  const handleClose = () => setConnectOpen(false);
+  const handleSuccess = () => {
+    // Redirect or update UI after successful login
+    window.location.reload();
+  };
+
+  return (
+    <SessionProvider serviceHost="/">
+      <div className="main-content">
+        <SessionConsumer>
+          {({ session }) => {
+            if (session.loading) {
+              return <div>Loading session...</div>;
+            }
+
+            return session.user ? (
+              <div>
+                <h2>Welcome, {session.user.did}!</h2>
+                <button onClick={() => session.logout()}>Logout</button>
+              </div>
+            ) : (
+              <Button onClick={() => setConnectOpen(true)}>Connect Wallet</Button>
+            );
+          }}
+        </SessionConsumer>
+      </div>
+
+      <DidConnect
+        popup
+        open={isConnectOpen}
+        action="login"
+        checkFn={axios.get}
+        onClose={handleClose}
+        onSuccess={handleSuccess}
+        messages={{
+          title: 'Login to My App',
+          scan: 'Scan QR code with your DID Wallet',
+          confirm: 'Confirm login on your wallet',
+          success: 'You have successfully signed in!',
+        }}
+        webWalletUrl={webWalletUrl}
+      />
+    </SessionProvider>
+  );
+}
+
+export default App;
+```
+
+This example demonstrates how to manage user sessions and trigger the login process with just a few components.
+
+### Next Steps
+
+Now that you have a basic understanding of the library, you're ready to dive deeper.
+
+<x-card data-title="Getting Started" data-href="/getting-started" data-icon="lucide:rocket" data-cta="Start Building">
+  Follow our step-by-step guide to integrate DID Connect into your own application from scratch.
+</x-card>