@arcblock/did-connect-react 3.1.40 → 3.1.42

package/docs/core-components-session-provider.zh-TW.md

@@ -0,0 +1,239 @@
+# Session 管理 (SessionProvider)
+
+`SessionProvider` 是 `@arcblock/did-connect-react` 函式庫的基石。它是一個 React Context Provider，封裝了所有與 session 相關的邏輯、狀態和操作。透過用 `SessionProvider` 包裹您的應用程式，您可以將使用者的 session 資訊和身份驗證方法提供給應用程式樹中的任何元件，而無需手動向下傳遞 props。
+
+該元件處理從儲存 session token 和管理使用者資料到協調登入/登出流程以及自動刷新 session 的所有事務。
+
+## 運作原理
+
+`SessionProvider` 建立一個 session context，其中包含目前使用者的狀態（`user` 物件、`loading` 狀態等），並提供修改該狀態的函式（例如，`login`、`logout`）。任何巢狀在 `SessionProvider` 內的元件都可以訂閱此 context 以存取這些資料並觸發身份驗證操作。
+
+這是一個說明基本架構的圖表：
+
+```d2 SessionProvider Architecture icon=mdi:react
+direction: down
+
+SessionProvider: {
+  label: "SessionProvider"
+  shape: rectangle
+  style: {
+    fill: "#f0f9ff"
+    stroke: "#0284c7"
+  }
+
+  Session-Context: {
+    label: "Session Context\n{ user, login(), logout() ... }"
+    shape: cylinder
+    style.fill: "#ecfdf5"
+  }
+
+  Your-App: {
+    label: "您的應用程式"
+    shape: rectangle
+
+    Header: {
+      label: "Header 元件"
+    }
+
+    ProfilePage: {
+      label: "個人資料頁面"
+    }
+
+    LoginButton: {
+      label: "登入按鈕"
+    }
+  }
+
+  Session-Context -> Your-App: 提供
+}
+
+Your-App.Header: 使用
+Your-App.ProfilePage: 使用
+Your-App.LoginButton: 使用與操作
+
+Your-App.Header -> Session-Context
+Your-App.ProfilePage -> Session-Context
+Your-App.LoginButton -> Session-Context
+```
+
+## 入門指南
+
+要使用 session 管理功能，您首先需要匯入 `SessionProvider` 並用它包裹您的應用程式。該函式庫匯出工廠函式以建立一個已配置的 provider。
+
+### 基本設定
+
+設定 provider 最常見的方法是使用 `createAuthServiceSessionContext`，它已為在 ArcBlock 生態系統（Blocklets）內執行的應用程式預先配置。
+
+```javascript App.js icon=logos:javascript
+import React from 'react';
+import { createAuthServiceSessionContext } from '@arcblock/did-connect-react/lib/Session';
+import AuthButton from './AuthButton';
+
+// 建立 SessionProvider 和一個用於存取 context 的 hook
+const { SessionProvider, SessionContext } = createAuthServiceSessionContext();
+
+export const useSession = () => React.useContext(SessionContext);
+
+export default function App() {
+  return (
+    <SessionProvider>
+      <div className="App">
+        <h1>歡迎使用 DID Connect</h1>
+        <AuthButton />
+      </div>
+    </SessionProvider>
+  );
+}
+```
+
+```javascript AuthButton.js icon=logos:javascript
+import React from 'react';
+import { useSession } from './App';
+
+export default function AuthButton() {
+  const { session } = useSession();
+
+  if (session.loading) {
+    return <div>載入中...</div>;
+  }
+
+  if (session.user) {
+    return (
+      <div>
+        <p>歡迎，{session.user.fullName || session.user.did}</p>
+        <button onClick={() => session.logout()}>登出</button>
+      </div>
+    );
+  }
+
+  return <button onClick={() => session.login()}>登入</button>;
+}
+```
+
+在此範例中，`createAuthServiceSessionContext` 產生一個 `SessionProvider`。我們用它包裹 `App`，現在任何子元件，例如 `AuthButton`，都可以使用 `useSession` hook 來存取 session 資料和函式。
+
+## SessionProvider Props
+
+您可以透過傳遞各種 props 來設定 `SessionProvider` 的行為。
+
+<x-field-group>
+  <x-field data-name="serviceHost" data-type="string" data-desc="驗證服務後端的基礎 URL。預設為目前 Blocklet 的前綴或 '/'。"></x-field>
+  <x-field data-name="autoConnect" data-type="boolean" data-default="false" data-desc="若為 true，如果在頁面載入時未找到使用者 session，DID Connect 對話方塊將自動開啟。"></x-field>
+  <x-field data-name="autoDisconnect" data-type="boolean" data-default="true" data-desc="若為 true，如果應用程式 ID 與 session cookie 中儲存的 ID 不符，session 將被自動清除。"></x-field>
+  <x-field data-name="protectedRoutes" data-type="string[]" data-default='["*"]' data-desc="一個用於保護路由模式的陣列。如果未經身份驗證的使用者嘗試存取這些路由，他們將看到一個載入指示器，直到 session 解析完成。支援萬用字元（*）。"></x-field>
+  <x-field data-name="locale" data-type="string" data-desc="設定 DID Connect UI 的顯示語言。預設為瀏覽器的語言。"></x-field>
+  <x-field data-name="webWalletUrl" data-type="string" data-desc="用於連接過程的網頁版 DID Wallet 的 URL。"></x-field>
+  <x-field data-name="timeout" data-type="number" data-default="120000" data-desc="在連接過程中等待 DID Wallet 回應的逾時時間（毫秒）。"></x-field>
+  <x-field data-name="useSocket" data-type="boolean" data-default="true" data-desc="決定是否使用 WebSocket 與錢包進行即時通訊，以提供更快的用戶體驗。"></x-field>
+  <x-field data-name="extraParams" data-type="object" data-desc="一個包含額外參數的物件，這些參數將隨每次驗證請求發送到後端。"></x-field>
+</x-field-group>
+
+## Session Context 物件
+
+當您使用 `SessionContext` 時，您會得到一個包含 session 狀態和 API 的物件。主要屬性是 `session`，它包含您將與之互動的所有資料和方法。
+
+### 狀態屬性
+
+這些是唯讀屬性，描述了使用者 session 的目前狀態。
+
+<x-field-group>
+  <x-field data-name="user" data-type="User | null" data-desc="如果 session 存在，則為經過身份驗證的使用者物件，否則為 null。包含 DID、姓名、電子郵件、頭像等詳細資訊。"></x-field>
+  <x-field data-name="loading" data-type="boolean" data-desc="當 session 正在初始化、刷新或在登入/登出過程中為 true。"></x-field>
+  <x-field data-name="initialized" data-type="boolean" data-desc="頁面載入時，初始 session 檢查完成後為 true。"></x-field>
+  <x-field data-name="open" data-type="boolean" data-desc="如果 DID Connect 對話方塊目前處於開啟狀態，則為 true。"></x-field>
+  <x-field data-name="error" data-type="string" data-desc="如果上一次 session 操作失敗，則包含錯誤訊息。"></x-field>
+  <x-field data-name="provider" data-type="string" data-desc="上次登入使用的提供者（例如 'wallet'、'github'、'google'）。"></x-field>
+  <x-field data-name="walletOS" data-type="string" data-desc="已連接的 DID Wallet 的作業系統（例如 'ios'、'android'、'web'）。"></x-field>
+  <x-field data-name="unReadCount" data-type="number" data-desc="目前使用者的未讀通知數量。"></x-field>
+</x-field-group>
+
+### 操作方法
+
+這些是您可以呼叫以啟動身份驗證流程或管理 session 的函式。
+
+<x-field-group>
+  <x-field data-name="login()" data-type="function">
+    <x-field-desc markdown>透過開啟 DID Connect UI 來啟動使用者登入流程。它接受可選的回呼函式和參數。</x-field-desc>
+  </x-field>
+  <x-field data-name="logout()" data-type="function">
+    <x-field-desc markdown>將目前使用者登出，並從儲存空間中清除 session。它接受一個可選的回呼函式，在完成後執行。</x-field-desc>
+  </x-field>
+  <x-field data-name="switchDid()" data-type="function">
+    <x-field-desc markdown>允許已登入的使用者切換到不同的 DID 帳戶。它會重新開啟 DID Connect UI，並提供切換帳戶的上下文。</x-field-desc>
+  </x-field>
+  <x-field data-name="bindWallet()" data-type="function">
+    <x-field-desc markdown>對於透過社群提供者（OAuth）或 Passkeys 登入的使用者，此函式會啟動一個流程，將 DID Wallet 連接到他們現有的帳戶。</x-field-desc>
+  </x-field>
+  <x-field data-name="refresh()" data-type="function">
+    <x-field-desc markdown>手動觸發從伺服器刷新使用者 session 資料。適用於獲取更新的個人資料資訊或權限。</x-field-desc>
+  </x-field>
+  <x-field data-name="switchProfile()" data-type="function">
+    <x-field-desc markdown>開啟 DID Connect UI，允許使用者在同一個 DID 帳戶內切換不同的個人資料（例如，個人、工作）。</x-field-desc>
+  </x-field>
+  <x-field data-name="switchPassport()" data-type="function">
+    <x-field-desc markdown>開啟 DID Connect UI，允許使用者在不同的通行證之間切換，這些通行證可能代表不同的憑證集或角色。</x-field-desc>
+  </x-field>
+  <x-field data-name="connectToDidSpaceForFullAccess()" data-type="function">
+    <x-field-desc markdown>啟動與使用者 DID Space 的連接，請求完全存取權限。這通常是需要讀取和寫入使用者個人資料儲存庫的應用程式所必需的。</x-field-desc>
+  </x-field>
+  <x-field data-name="withSecondaryAuth()" data-type="function">
+    <x-field-desc markdown>一個高階函式，它包裹另一個函式，要求使用者在執行被包裹的函式之前完成二次身份驗證步驟（例如，重新輸入密碼、使用 passkey）。這是保護敏感操作的理想選擇。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 事件訂閱
+
+context 還提供一個 `events` 物件，它是 `EventEmitter3` 的一個實例。您可以使用它來訂閱 session 的各種生命週期事件。
+
+```javascript EventListener.js icon=logos:javascript
+import React, { useEffect } from 'react';
+import { useSession } from './App';
+
+function EventListener() {
+  const { events } = useSession();
+
+  useEffect(() => {
+    const handleLogin = (result) => {
+      console.log('使用者已登入：', result.user.did);
+    };
+
+    const handleLogout = () => {
+      console.log('使用者已登出');
+    };
+
+    events.on('login', handleLogin);
+    events.on('logout', handleLogout);
+
+    // 在元件卸載時清除監聽器
+    return () => {
+      events.off('login', handleLogin);
+      events.off('logout', handleLogout);
+    };
+  }, [events]);
+
+  return null; // 此元件不渲染任何內容
+}
+```
+
+可用的事件包括 `login`、`login-failed`、`logout`、`change`、`bind-wallet`、`switch-passport` 等。
+
+## 進階自訂
+
+對於需要不同儲存機制或更精細控制的場景，您可以使用通用的 `createSessionContext` 工廠函式。
+
+```javascript customSession.js icon=logos:javascript
+import { createSessionContext } from '@arcblock/did-connect-react/lib/Session';
+
+const { SessionProvider, SessionContext } = createSessionContext(
+  'my_app_session_token', // 自訂儲存金鑰
+  'ls',                   // 使用 localStorage 而非 cookie
+  {},
+  {
+    rolling: false,         // 停用自動 token 刷新
+  }
+);
+
+// ... 根據需要匯出和使用
+```
+
+這允許您微調 session 行為，例如將儲存引擎更改為 `localStorage`（'ls'）或 `cookie`，或調整 token 刷新策略。

package/docs/core-components-session-provider.zh.md

@@ -0,0 +1,239 @@
+# 会话管理 (SessionProvider)
+
+`SessionProvider` 是 `@arcblock/did-connect-react` 库的基石。它是一个 React Context Provider，封装了所有与会话相关的逻辑、状态和操作。通过使用 `SessionProvider` 包装您的应用程序，您可以将用户的会话信息和身份验证方法提供给应用程序树中的任何组件，而无需手动向下传递 props。
+
+该组件处理从存储会话令牌和管理用户数据到协调登录/注销流程以及自动刷新会话的所有事务。
+
+## 工作原理
+
+`SessionProvider` 创建一个会话上下文，该上下文持有当前用户的状态（`user` 对象、`loading` 状态等）并提供修改该状态的函数（例如 `login`、`logout`）。嵌套在 `SessionProvider` 中的任何组件都可以订阅此上下文以访问此数据并触​​发身份验证操作。
+
+下图说明了基本架构：
+
+```d2 SessionProvider 架构 icon=mdi:react
+direction: down
+
+SessionProvider: {
+  label: "SessionProvider"
+  shape: rectangle
+  style: {
+    fill: "#f0f9ff"
+    stroke: "#0284c7"
+  }
+
+  Session-Context: {
+    label: "会话上下文\n{ user, login(), logout() ... }"
+    shape: cylinder
+    style.fill: "#ecfdf5"
+  }
+
+  Your-App: {
+    label: "您的应用程序"
+    shape: rectangle
+
+    Header: {
+      label: "Header 组件"
+    }
+
+    ProfilePage: {
+      label: "个人资料页面"
+    }
+
+    LoginButton: {
+      label: "登录按钮"
+    }
+  }
+
+  Session-Context -> Your-App: 提供
+}
+
+Your-App.Header: 消费
+Your-App.ProfilePage: 消费
+Your-App.LoginButton: 消费与操作
+
+Your-App.Header -> Session-Context
+Your-App.ProfilePage -> Session-Context
+Your-App.LoginButton -> Session-Context
+```
+
+## 快速入门
+
+要使用会话管理功能，您首先需要导入 `SessionProvider` 并用它包装您的应用程序。该库导出工厂函数以创建配置好的 provider。
+
+### 基本设置
+
+设置 provider 的最常见方法是使用 `createAuthServiceSessionContext`，它已为在 ArcBlock 生态系统 (Blocklets) 中运行的应用程序预先配置。
+
+```javascript App.js icon=logos:javascript
+import React from 'react';
+import { createAuthServiceSessionContext } from '@arcblock/did-connect-react/lib/Session';
+import AuthButton from './AuthButton';
+
+// 创建 SessionProvider 和一个用于访问上下文的 hook
+const { SessionProvider, SessionContext } = createAuthServiceSessionContext();
+
+export const useSession = () => React.useContext(SessionContext);
+
+export default function App() {
+  return (
+    <SessionProvider>
+      <div className="App">
+        <h1>Welcome to DID Connect</h1>
+        <AuthButton />
+      </div>
+    </SessionProvider>
+  );
+}
+```
+
+```javascript AuthButton.js icon=logos:javascript
+import React from 'react';
+import { useSession } from './App';
+
+export default function AuthButton() {
+  const { session } = useSession();
+
+  if (session.loading) {
+    return <div>Loading...</div>;
+  }
+
+  if (session.user) {
+    return (
+      <div>
+        <p>Welcome, {session.user.fullName || session.user.did}</p>
+        <button onClick={() => session.logout()}>Logout</button>
+      </div>
+    );
+  }
+
+  return <button onClick={() => session.login()}>Login</button>;
+}
+```
+
+在此示例中，`createAuthServiceSessionContext` 生成一个 `SessionProvider`。我们用它包装我们的 `App`，现在任何子组件，例如 `AuthButton`，都可以使用 `useSession` hook 来访问会话数据和函数。
+
+## SessionProvider Props
+
+您可以通过向 `SessionProvider` 传递各种 props 来配置其行为。
+
+<x-field-group>
+  <x-field data-name="serviceHost" data-type="string" data-desc="身份验证服务后端的基 URL。默认为当前 Blocklet 的前缀或 '/'。"></x-field>
+  <x-field data-name="autoConnect" data-type="boolean" data-default="false" data-desc="如果为 true，在页面加载时若未找到用户会话，则 DID Connect 对话框将自动打开。"></x-field>
+  <x-field data-name="autoDisconnect" data-type="boolean" data-default="true" data-desc="如果为 true，当应用程序 ID 与会话 cookie 中存储的 ID 不匹配时，会话将自动清除。"></x-field>
+  <x-field data-name="protectedRoutes" data-type="string[]" data-default='["*"]' data-desc="用于保护的路由模式数组。如果未经身份验证的用户尝试访问这些路由，他们将看到一个加载指示器，直到会话被解析。支持通配符 (*)。"></x-field>
+  <x-field data-name="locale" data-type="string" data-desc="设置 DID Connect UI 的显示语言。默认为浏览器语言。"></x-field>
+  <x-field data-name="webWalletUrl" data-type="string" data-desc="用于连接过程的基于 Web 的 DID Wallet 的 URL。"></x-field>
+  <x-field data-name="timeout" data-type="number" data-default="120000" data-desc="在连接过程中等待 DID Wallet 响应的超时时间（以毫秒为单位）。"></x-field>
+  <x-field data-name="useSocket" data-type="boolean" data-default="true" data-desc="决定是否使用 WebSocket 与钱包进行实时通信，以提供更快的用户体验。"></x-field>
+  <x-field data-name="extraParams" data-type="object" data-desc="一个包含额外参数的对象，这些参数将随每次身份验证请求发送到后端。"></x-field>
+</x-field-group>
+
+## 会话上下文对象
+
+当您使用 `SessionContext` 时，会得到一个包含会话状态和 API 的对象。主要属性是 `session`，它包含了您将要交互的所有数据和方法。
+
+### 状态属性
+
+这些是描述用户会话当前状态的只读属性。
+
+<x-field-group>
+  <x-field data-name="user" data-type="User | null" data-desc="如果存在会话，则为经过身份验证的用户对象，否则为 null。包含 DID、姓名、电子邮件、头像等详细信息。"></x-field>
+  <x-field data-name="loading" data-type="boolean" data-desc="在会话初始化、刷新或登录/注销过程中为 True。"></x-field>
+  <x-field data-name="initialized" data-type="boolean" data-desc="页面加载时初始会话检查完成后为 True。"></x-field>
+  <x-field data-name="open" data-type="boolean" data-desc="如果 DID Connect 对话框当前处于打开状态，则为 True。"></x-field>
+  <x-field data-name="error" data-type="string" data-desc="如果上次会话操作失败，则包含错误消息。"></x-field>
+  <x-field data-name="provider" data-type="string" data-desc="上次登录使用的提供商（例如 'wallet'、'github'、'google'）。"></x-field>
+  <x-field data-name="walletOS" data-type="string" data-desc="已连接的 DID Wallet 的操作系统（例如 'ios'、'android'、'web'）。"></x-field>
+  <x-field data-name="unReadCount" data-type="number" data-desc="当前用户的未读通知数量。"></x-field>
+</x-field-group>
+
+### 操作方法
+
+这些是您可以调用以启动身份验证流程或管理会话的函数。
+
+<x-field-group>
+  <x-field data-name="login()" data-type="function">
+    <x-field-desc markdown>通过打开 DID Connect UI 来启动用户登录过程。它接受可选的回调和参数。</x-field-desc>
+  </x-field>
+  <x-field data-name="logout()" data-type="function">
+    <x-field-desc markdown>将当前用户登出，从存储中清除会话。它接受一个可选的回调函数，在完成后执行。</x-field-desc>
+  </x-field>
+  <x-field data-name="switchDid()" data-type="function">
+    <x-field-desc markdown>允许已登录的用户切换到不同的 DID 账户。它会重新打开 DID Connect UI，并提供切换账户的上下文。</x-field-desc>
+  </x-field>
+  <x-field data-name="bindWallet()" data-type="function">
+    <x-field-desc markdown>对于通过社交提供商（OAuth）或 Passkeys 登录的用户，此函数会启动一个流程，将 DID Wallet 连接到他们现有的账户。</x-field-desc>
+  </x-field>
+  <x-field data-name="refresh()" data-type="function">
+    <x-field-desc markdown>手动触发从服务器刷新用户会话数据。可用于获取更新的个人资料信息或权限。</x-field-desc>
+  </x-field>
+  <x-field data-name="switchProfile()" data-type="function">
+    <x-field-desc markdown>打开 DID Connect UI，允许用户在同一 DID 账户内的不同个人资料（例如，个人、工作）之间切换。</x-field-desc>
+  </x-field>
+  <x-field data-name="switchPassport()" data-type="function">
+    <x-field-desc markdown>打开 DID Connect UI，允许用户在不同 passport 之间切换，这些 passport 可能代表不同的凭证或角色集。</x-field-desc>
+  </x-field>
+  <x-field data-name="connectToDidSpaceForFullAccess()" data-type="function">
+    <x-field-desc markdown>启动与用户 DID Space 的连接，请求完全访问权限。这通常是需要在用户个人数据存储中读写数据的应用程序所必需的。</x-field-desc>
+  </x-field>
+  <x-field data-name="withSecondaryAuth()" data-type="function">
+    <x-field-desc markdown>一个高阶函数，用于包装另一个函数，在执行被包装的函数之前，要求用户完成二次身份验证步骤（例如，重新输入密码、使用 passkey）。这是保护敏感操作的理想选择。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 事件订阅
+
+该上下文还提供一个 `events` 对象，它是 `EventEmitter3` 的一个实例。您可以使用它来订阅会话的各种生命周期事件。
+
+```javascript EventListener.js icon=logos:javascript
+import React, { useEffect } from 'react';
+import { useSession } from './App';
+
+function EventListener() {
+  const { events } = useSession();
+
+  useEffect(() => {
+    const handleLogin = (result) => {
+      console.log('用户已登录：', result.user.did);
+    };
+
+    const handleLogout = () => {
+      console.log('用户已登出');
+    };
+
+    events.on('login', handleLogin);
+    events.on('logout', handleLogout);
+
+    // 在组件卸载时清理监听器
+    return () => {
+      events.off('login', handleLogin);
+      events.off('logout', handleLogout);
+    };
+  }, [events]);
+
+  return null; // 此组件不渲染任何内容
+}
+```
+
+可用的事件包括 `login`、`login-failed`、`logout`、`change`、`bind-wallet`、`switch-passport` 等。
+
+## 高级定制
+
+对于需要不同存储机制或更精细控制的场景，您可以使用通用的 `createSessionContext` 工厂函数。
+
+```javascript customSession.js icon=logos:javascript
+import { createSessionContext } from '@arcblock/did-connect-react/lib/Session';
+
+const { SessionProvider, SessionContext } = createSessionContext(
+  'my_app_session_token', // 自定义存储键
+  'ls',                   // 使用 localStorage 代替 cookie
+  {},
+  {
+    rolling: false,         // 禁用自动令牌刷新
+  }
+);
+
+// ... 根据需要导出和使用
+```
+
+这允许您微调会话行为，例如将存储引擎更改为 `localStorage` ('ls') 或 `cookie`，或调整令牌刷新策略。

package/docs/core-components.ja.md

@@ -0,0 +1,16 @@
+# コアコンポーネント
+
+`@arcblock/did-connect-react` ライブラリは、分散型アイデンティティをアプリケーションに統合するための基盤を提供するいくつかの重要なコンポーネントを中心に構築されています。これらのコンポーネントは、セッション管理とユーザー向けの接続インターフェースを処理します。
+
+これら2つのコアコンポーネントを理解することは、ライブラリをマスターするための第一歩です。これらは連携して、シームレスで安全な認証体験を提供します。
+
+<x-cards data-columns="2">
+  <x-card data-title="SessionProvider" data-icon="lucide:key-round" data-href="/core-components/session-provider">
+    ライブラリの中心です。このプロバイダーはアプリケーションをラップして、ユーザーセッションの状態を管理し、認証ロジックを処理し、セッションデータと制御関数をすべてのネストされたコンポーネントに公開します。
+  </x-card>
+  <x-card data-title="DidConnect" data-icon="lucide:qr-code" data-href="/core-components/did-connect">
+    ユーザーインタラクションのための事前構築済みUIです。QRコード、ログインオプション（パスキーやOAuthなど）を表示し、接続フロー全体を処理します。通常、直接レンダリングするのではなく、プログラムで制御します。
+  </x-card>
+</x-cards>
+
+まず、アプリケーション全体の状態を管理するために `SessionProvider` を設定する方法を学び、次に `DidConnect` コンポーネントがユーザー認証の過程をどのように促進するかを探ります。

package/docs/core-components.md

@@ -0,0 +1,16 @@
+# Core Components
+
+The `@arcblock/did-connect-react` library is built around a few essential components that provide the foundation for integrating decentralized identity into your application. These components handle session management and the user-facing connection interface.
+
+Understanding these two core components is the first step to mastering the library. They work together to provide a seamless and secure authentication experience.
+
+<x-cards data-columns="2">
+  <x-card data-title="SessionProvider" data-icon="lucide:key-round" data-href="/core-components/session-provider">
+    The heart of the library. This provider wraps your application to manage user session state, handle authentication logic, and expose session data and control functions to all nested components.
+  </x-card>
+  <x-card data-title="DidConnect" data-icon="lucide:qr-code" data-href="/core-components/did-connect">
+    The pre-built UI for user interaction. It displays the QR code, login options (like Passkeys and OAuth), and handles the entire connection flow. You typically won't render it directly but control it programmatically.
+  </x-card>
+</x-cards>
+
+Start by learning how to set up the `SessionProvider` to manage application-wide state, then explore how the `DidConnect` component facilitates the user authentication journey.

package/docs/core-components.zh-TW.md

@@ -0,0 +1,16 @@
+# 核心元件
+
+`@arcblock/did-connect-react` 函式庫圍繞著幾個核心元件構建，這些元件為將去中心化身份整合到您的應用程式中提供了基礎。這些元件處理會話管理和使用者面向的連接介面。
+
+理解這兩個核心元件是掌握此函式庫的第一步。它們共同提供無縫且安全的身份驗證體驗。
+
+<x-cards data-columns="2">
+  <x-card data-title="SessionProvider" data-icon="lucide:key-round" data-href="/core-components/session-provider">
+    函式庫的核心。此提供者包裝您的應用程式，以管理使用者會話狀態、處理身份驗證邏輯，並將會話資料和控制函式公開給所有巢狀元件。
+  </x-card>
+  <x-card data-title="DidConnect" data-icon="lucide:qr-code" data-href="/core-components/did-connect">
+    預先建置的使用者互動介面。它顯示 QR code、登入選項（如密碼金鑰和 OAuth），並處理整個連接流程。您通常不會直接渲染它，而是以程式化方式控制它。
+  </x-card>
+</x-cards>
+
+首先學習如何設定 `SessionProvider` 來管理應用程式範圍的狀態，然後探索 `DidConnect` 元件如何促進使用者身份驗證的旅程。

package/docs/core-components.zh.md

@@ -0,0 +1,16 @@
+# 核心组件
+
+`@arcblock/did-connect-react` 库围绕几个核心组件构建，它们为将去中心化身份集成到您的应用程序中提供了基础。这些组件处理会话管理和面向用户的连接界面。
+
+理解这两个核心组件是掌握该库的第一步。它们协同工作，提供无缝且安全的身份验证体验。
+
+<x-cards data-columns="2">
+  <x-card data-title="SessionProvider" data-icon="lucide:key-round" data-href="/core-components/session-provider">
+    该库的核心。此提供程序包裹您的应用程序，用于管理用户会话状态、处理身份验证逻辑，并向所有嵌套组件公开会话数据和控制函数。
+  </x-card>
+  <x-card data-title="DidConnect" data-icon="lucide:qr-code" data-href="/core-components/did-connect">
+    用于用户交互的预构建 UI。它会显示二维码、登录选项（如 Passkeys 和 OAuth），并处理整个连接流程。您通常不会直接渲染它，而是以编程方式对其进行控制。
+  </x-card>
+</x-cards>
+
+首先学习如何设置 `SessionProvider` 来管理整个应用程序的状态，然后探索 `DidConnect` 组件如何为用户的身份验证过程提供便利。