@arcblock/did-connect-react 3.1.40 → 3.1.42

package/docs/hooks-use-connect.ja.md

@@ -0,0 +1,214 @@
+# useConnect
+
+`useConnect`フックは、`DidConnect` UIモーダルをプログラムで開閉・管理するための強力な方法を提供します。宣言的な`Button`コンポーネントが提供するものよりも接続フローをより詳細に制御する必要がある場合、例えばカスタムUI要素、メニュー項目、またはアプリケーションイベントに応じてモーダルをトリガーする場合に理想的なソリューションです。
+
+このフックは`Button`コンポーネントの背後にあるエンジンであり、同じコア機能への直接アクセスを提供します。
+
+## 仕組み
+
+`useConnect`フックは、主に2つの要素を返します：
+
+1.  **`connectHolder`**：コンポーネントツリーにレンダリングする必要があるReact要素です。この要素は、`DidConnect`モーダルがアクティブ化されたときにそれをレンダリングする責任があります。`open`関数が呼び出されるまで非表示のままです。
+2.  **`connectApi`**：モーダルのライフサイクルを制御するために使用する関数（`open`、`close`、`openPopup`、`loginOAuth`）を含むオブジェクトです。
+
+```d2
+direction: down
+
+User: { 
+  shape: c4-person 
+}
+
+Your-App: {
+  label: "あなたのアプリケーション"
+  shape: rectangle
+
+  Custom-Button: {
+    label: "カスタムボタン"
+  }
+
+  useConnect-Hook: {
+    label: "useConnect()"
+  }
+  
+  connectHolder: {
+    label: "connectHolder"
+  }
+}
+
+DID-Wallet: {
+  label: "DID Wallet"
+  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
+}
+
+User -> Your-App.Custom-Button: "1. クリック"
+Your-App.Custom-Button -> Your-App.useConnect-Hook: "2. connectApi.open() を呼び出す"
+Your-App.useConnect-Hook -> Your-App.connectHolder: "3. モーダルを有効化"
+Your-App.connectHolder -> User: "4. DidConnect UI を表示"
+User -> DID-Wallet: "5. QRをスキャンして承認"
+DID-Wallet -> Your-App.connectHolder: "6. レスポンスを送信"
+Your-App.connectHolder -> Your-App.useConnect-Hook: "7. onSuccess コールバックをトリガー"
+Your-App.useConnect-Hook -> Your-App.connectHolder: "8. モーダルを無効化"
+
+```
+
+## セットアップ
+
+フックを使用するには、それをインポートし、コンポーネント内で呼び出します。次に、アプリケーションのどこか、できればトップレベルのコンポーネントで`connectHolder`をレンダリングして、モーダルが他のすべてのコンテンツの上にオーバーレイできるようにします。
+
+```javascript Basic Setup icon=logos:javascript
+import React from 'react';
+import { useConnect } from '@arcblock/did-connect-react';
+
+function MyComponent() {
+  // 1. フックを初期化する
+  const { connectHolder, connectApi } = useConnect();
+
+  const handleLogin = () => {
+    // 2. API を使用してモーダルを開く
+    connectApi.open({
+      action: 'login',
+      onSuccess: (result) => {
+        console.log('ログイン成功！', result);
+      },
+      onClose: () => {
+        console.log('モーダルがユーザーによって閉じられました。');
+      }
+    });
+  };
+
+  return (
+    <div>
+      <button type="button" onClick={handleLogin}>
+        DIDでログイン
+      </button>
+
+      {/* 3. ホルダーコンポーネントをレンダリングする */}
+      {connectHolder}
+    </div>
+  );
+}
+
+export default MyComponent;
+```
+
+## APIリファレンス
+
+`connectApi`オブジェクトは、接続プロセスを制御するための以下のメソッドを提供します。
+
+### `connectApi.open(options)`
+
+これは`DidConnect`モーダルをトリガーして表示するための主要な関数です。接続セッションの動作、外観、およびコールバックを設定するための単一の`options`オブジェクトを受け入れます。
+
+**パラメータ (`options`)**
+
+<x-field-group>
+  <x-field data-name="action" data-type="string" data-required="true">
+    <x-field-desc markdown>接続リクエストの目的、例：`login`、`claim`、`sign`など。これはウォレット内のワークフローを決定します。</x-field-desc>
+  </x-field>
+  <x-field data-name="onSuccess" data-type="(result: object) => void" data-required="false">
+    <x-field-desc markdown>ユーザーがウォレットでアクションを正常に完了したときに実行されるコールバック関数。`result`オブジェクトにはウォレットからのレスポンスが含まれます。</x-field-desc>
+  </x-field>
+  <x-field data-name="onClose" data-type="() => void" data-required="false">
+    <x-field-desc markdown>ユーザーがアクションを完了せずに手動でモーダルを閉じたときに実行されるコールバック関数。</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="(error: any) => void" data-required="false">
+    <x-field-desc markdown>タイムアウトやネットワークの問題など、プロセス中にエラーが発生した場合に実行されるコールバック関数。</x-field-desc>
+  </x-field>
+  <x-field data-name="messages" data-type="ConnectMessages" data-required="false">
+    <x-field-desc markdown>モーダルに表示されるテキストをカスタマイズするためのオブジェクト。詳細は`ConnectMessages`型を参照してください。</x-field-desc>
+    <x-field data-name="title" data-type="string" data-desc="モーダルのタイトル。"></x-field>
+    <x-field data-name="scan" data-type="string" data-desc="QRコードに付随するテキスト。"></x-field>
+    <x-field data-name="confirm" data-type="string" data-desc="確認ステップのテキスト。"></x-field>
+    <x-field data-name="success" data-type="ReactNode" data-desc="成功画面のコンテンツ。"></x-field>
+  </x-field>
+  <x-field data-name="popup" data-type="boolean" data-default="true">
+    <x-field-desc markdown>`true`の場合、UIはモーダルダイアログとして表示されます。`false`の場合、インラインでレンダリングされ、`containerEl`の設定が必要です。</x-field-desc>
+  </x-field>
+  <x-field data-name="containerEl" data-type="Element" data-required="false">
+    <x-field-desc markdown>`popup`が`false`に設定されている場合に`DidConnect`コンポーネントがレンダリングされるDOM要素。</x-field-desc>
+  </x-field>
+  <x-field data-name="closeTimeout" data-type="number" data-default="2000">
+    <x-field-desc markdown>接続成功後、モーダルが自動的に閉じるまでの遅延時間（ミリ秒）。</x-field-desc>
+  </x-field>
+  <x-field data-name="checkInterval" data-type="number" data-default="2000">
+    <x-field-desc markdown>セッションステータスを確認するためにサーバーをポーリングする間隔（ミリ秒）。</x-field-desc>
+  </x-field>
+  <x-field data-name="checkTimeout" data-type="number" data-default="300000">
+    <x-field-desc markdown>接続試行がタイムアウトするまでの合計時間（ミリ秒）。</x-field-desc>
+  </x-field>
+  <x-field data-name="extraParams" data-type="object" data-default="{}">
+    <x-field-desc markdown>セッション作成リクエストに含める追加のパラメータで、サーバー側で取得できます。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### `connectApi.close()`
+
+`DidConnect`モーダルを手動で閉じます。モーダルは成功時またはユーザーによるキャンセル時に自動的に閉じますが、他の理由でプログラムから閉じる必要がある場合はこの関数を呼び出すことができます。
+
+```javascript icon=lucide:x-circle
+// 例：成功コールバックで短い遅延の後にモーダルを閉じる
+connectApi.open({
+  action: 'login',
+  onSuccess: () => {
+    showTemporarySuccessMessage();
+    setTimeout(() => {
+      connectApi.close();
+    }, 1500);
+  },
+  closeTimeout: 999999 // 自動クローズを防止
+});
+```
+
+### `connectApi.openPopup(params, options)`
+
+この関数は、現在のページ内のモーダルの代わりに、新しいブラウザのポップアップウィンドウでDID Connectフローを開く代替の接続方法を提供します。これは、特定のOAuthのようなフローや、モーダルを注入できないサイトとの統合に役立ちます。
+
+**パラメータ**
+
+<x-field-group>
+  <x-field data-name="params" data-type="ConnectProps" data-required="true">
+    <x-field-desc markdown>`open`メソッドのオプションに似ています。主な違いは、認証方法（例：「github」、「google」）を識別するために`params.extraParams.provider`が**必須**であることです。</x-field-desc>
+  </x-field>
+  <x-field data-name="options" data-type="object" data-required="false">
+    <x-field-desc markdown>ポップアップウィンドウ自体の設定。</x-field-desc>
+    <x-field data-name="baseUrl" data-type="string" data-desc="ポップアップURLを構築するためのベースURL。"></x-field>
+    <x-field data-name="locale" data-type="string" data-default="en" data-desc="ポップアップコンテンツのロケール。"></x-field>
+    <x-field data-name="popupOptions" data-type="object" data-desc="ポップアップのサイズや機能をカスタマイズするために`window.open()`に直接渡されるオプション。"></x-field>
+  </x-field>
+</x-field-group>
+
+**使用法**
+
+`openPopup`関数は、成功時に認証データで解決されるか、失敗またはキャンセル時に拒否される`Promise`を返します。
+
+```javascript icon=lucide:external-link
+const handleGithubLogin = async () => {
+  try {
+    const result = await connectApi.openPopup({
+      action: 'login',
+      onSuccess: () => console.log('このコールバックもトリガーされます'),
+      extraParams: { provider: 'github' } // これは必須です
+    });
+    console.log('ポップアップ経由でのログイン成功：', result);
+  } catch (err) {
+    if (err.message === 'Popup closed') {
+      console.log('ユーザーがポップアップウィンドウを閉じました。');
+    } else {
+      console.error('エラーが発生しました：', err);
+    }
+  }
+};
+```
+
+### `connectApi.loginOAuth(options)`
+
+これはOAuthログインフローを直接開始するためのヘルパー関数です。ライブラリの他の部分で内部的に使用される低レベルのユーティリティです。
+
+**パラメータ (`options`)**
+
+<x-field-group>
+  <x-field data-name="provider" data-type="string" data-required="true" data-desc="使用するOAuthプロバイダー、例：「github」、「google」。"></x-field>
+  <x-field data-name="action" data-type="string" data-required="true" data-desc="アクション、通常は「login」。"></x-field>
+  <x-field data-name="extraParams" data-type="object" data-required="false" data-desc="OAuthフローの追加パラメータ。"></x-field>
+  <x-field data-name="onLogin" data-type="function" data-required="true" data-desc="ログイン成功時に実行されるコールバック関数。"></x-field>
+</x-field-group>

package/docs/hooks-use-connect.md

@@ -0,0 +1,214 @@
+# useConnect
+
+The `useConnect` hook provides a powerful, programmatic way to open, close, and manage the `DidConnect` UI modal. It's the ideal solution when you need more control over the connection flow than the declarative `Button` component offers, such as triggering the modal from a custom UI element, a menu item, or in response to an application event.
+
+This hook is the engine behind the `Button` component and gives you direct access to the same core functionalities.
+
+## How It Works
+
+The `useConnect` hook returns two main elements:
+
+1.  **`connectHolder`**: A React element that must be rendered in your component tree. This element is responsible for rendering the `DidConnect` modal when it's activated. It remains invisible until the `open` function is called.
+2.  **`connectApi`**: An object containing the functions (`open`, `close`, `openPopup`, `loginOAuth`) you'll use to control the modal's lifecycle.
+
+```d2
+direction: down
+
+User: { 
+  shape: c4-person 
+}
+
+Your-App: {
+  label: "Your Application"
+  shape: rectangle
+
+  Custom-Button: {
+    label: "Custom Button"
+  }
+
+  useConnect-Hook: {
+    label: "useConnect()"
+  }
+  
+  connectHolder: {
+    label: "connectHolder"
+  }
+}
+
+DID-Wallet: {
+  label: "DID Wallet"
+  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
+}
+
+User -> Your-App.Custom-Button: "1. Clicks"
+Your-App.Custom-Button -> Your-App.useConnect-Hook: "2. Calls connectApi.open()"
+Your-App.useConnect-Hook -> Your-App.connectHolder: "3. Activates modal"
+Your-App.connectHolder -> User: "4. Displays DidConnect UI"
+User -> DID-Wallet: "5. Scans QR & Approves"
+DID-Wallet -> Your-App.connectHolder: "6. Sends response"
+Your-App.connectHolder -> Your-App.useConnect-Hook: "7. Triggers onSuccess callback"
+Your-App.useConnect-Hook -> Your-App.connectHolder: "8. Deactivates modal"
+
+```
+
+## Setup
+
+To use the hook, import it and call it within your component. Then, ensure you render the `connectHolder` somewhere in your application, preferably at a top-level component to ensure the modal can overlay all other content.
+
+```javascript Basic Setup icon=logos:javascript
+import React from 'react';
+import { useConnect } from '@arcblock/did-connect-react';
+
+function MyComponent() {
+  // 1. Initialize the hook
+  const { connectHolder, connectApi } = useConnect();
+
+  const handleLogin = () => {
+    // 2. Use the API to open the modal
+    connectApi.open({
+      action: 'login',
+      onSuccess: (result) => {
+        console.log('Login successful!', result);
+      },
+      onClose: () => {
+        console.log('Modal closed by user.');
+      }
+    });
+  };
+
+  return (
+    <div>
+      <button type="button" onClick={handleLogin}>
+        Login with DID
+      </button>
+
+      {/* 3. Render the holder component */}
+      {connectHolder}
+    </div>
+  );
+}
+
+export default MyComponent;
+```
+
+## API Reference
+
+The `connectApi` object provides the following methods to control the connection process.
+
+### `connectApi.open(options)`
+
+This is the primary function to trigger and display the `DidConnect` modal. It accepts a single `options` object to configure the behavior, appearance, and callbacks for the connection session.
+
+**Parameters (`options`)**
+
+<x-field-group>
+  <x-field data-name="action" data-type="string" data-required="true">
+    <x-field-desc markdown>The purpose of the connection request, e.g., `login`, `claim`, `sign`, etc. This determines the workflow within the wallet.</x-field-desc>
+  </x-field>
+  <x-field data-name="onSuccess" data-type="(result: object) => void" data-required="false">
+    <x-field-desc markdown>Callback function executed when the user successfully completes the action in their wallet. The `result` object contains the response from the wallet.</x-field-desc>
+  </x-field>
+  <x-field data-name="onClose" data-type="() => void" data-required="false">
+    <x-field-desc markdown>Callback function executed when the user manually closes the modal without completing the action.</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="(error: any) => void" data-required="false">
+    <x-field-desc markdown>Callback function executed if an error occurs during the process, such as a timeout or a network issue.</x-field-desc>
+  </x-field>
+  <x-field data-name="messages" data-type="ConnectMessages" data-required="false">
+    <x-field-desc markdown>An object to customize the text displayed in the modal. See `ConnectMessages` type for details.</x-field-desc>
+    <x-field data-name="title" data-type="string" data-desc="Modal title."></x-field>
+    <x-field data-name="scan" data-type="string" data-desc="Text accompanying the QR code."></x-field>
+    <x-field data-name="confirm" data-type="string" data-desc="Text for the confirmation step."></x-field>
+    <x-field data-name="success" data-type="ReactNode" data-desc="Content for the success screen."></x-field>
+  </x-field>
+  <x-field data-name="popup" data-type="boolean" data-default="true">
+    <x-field-desc markdown>If `true`, the UI is displayed as a modal dialog. If `false`, it renders inline, requiring `containerEl` to be set.</x-field-desc>
+  </x-field>
+  <x-field data-name="containerEl" data-type="Element" data-required="false">
+    <x-field-desc markdown>A DOM element where the `DidConnect` component will be rendered if `popup` is set to `false`.</x-field-desc>
+  </x-field>
+  <x-field data-name="closeTimeout" data-type="number" data-default="2000">
+    <x-field-desc markdown>The delay in milliseconds before the modal automatically closes after a successful connection.</x-field-desc>
+  </x-field>
+  <x-field data-name="checkInterval" data-type="number" data-default="2000">
+    <x-field-desc markdown>The interval in milliseconds for polling the server to check the session status.</x-field-desc>
+  </x-field>
+  <x-field data-name="checkTimeout" data-type="number" data-default="300000">
+    <x-field-desc markdown>The total time in milliseconds before the connection attempt times out.</x-field-desc>
+  </x-field>
+  <x-field data-name="extraParams" data-type="object" data-default="{}">
+    <x-field-desc markdown>Any extra parameters to be included in the session creation request, which can be retrieved on the server-side.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### `connectApi.close()`
+
+Manually closes the `DidConnect` modal. The modal closes automatically on success or user cancellation, but you can call this function if you need to close it programmatically for other reasons.
+
+```javascript icon=lucide:x-circle
+// Example: Close the modal after a short delay in the success callback
+connectApi.open({
+  action: 'login',
+  onSuccess: () => {
+    showTemporarySuccessMessage();
+    setTimeout(() => {
+      connectApi.close();
+    }, 1500);
+  },
+  closeTimeout: 999999 // Prevent auto-close
+});
+```
+
+### `connectApi.openPopup(params, options)`
+
+This function provides an alternative connection method that opens the DID Connect flow in a new browser popup window instead of a modal within the current page. This is useful for certain OAuth-like flows or when integrating with sites where you cannot inject a modal.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="params" data-type="ConnectProps" data-required="true">
+    <x-field-desc markdown>Similar to the `open` method's options. A key difference is that `params.extraParams.provider` is **required** to identify the authentication method (e.g., 'github', 'google').</x-field-desc>
+  </x-field>
+  <x-field data-name="options" data-type="object" data-required="false">
+    <x-field-desc markdown>Configuration for the popup window itself.</x-field-desc>
+    <x-field data-name="baseUrl" data-type="string" data-desc="The base URL for constructing the popup URL."></x-field>
+    <x-field data-name="locale" data-type="string" data-default="en" data-desc="The locale for the popup content."></x-field>
+    <x-field data-name="popupOptions" data-type="object" data-desc="Options passed directly to `window.open()` for customizing the popup's size and features."></x-field>
+  </x-field>
+</x-field-group>
+
+**Usage**
+
+The `openPopup` function returns a `Promise` that resolves with the authentication data on success or rejects on failure or cancellation.
+
+```javascript icon=lucide:external-link
+const handleGithubLogin = async () => {
+  try {
+    const result = await connectApi.openPopup({
+      action: 'login',
+      onSuccess: () => console.log('This callback is also triggered'),
+      extraParams: { provider: 'github' } // This is required
+    });
+    console.log('Login successful via popup:', result);
+  } catch (err) {
+    if (err.message === 'Popup closed') {
+      console.log('User closed the popup window.');
+    } else {
+      console.error('An error occurred:', err);
+    }
+  }
+};
+```
+
+### `connectApi.loginOAuth(options)`
+
+This is a helper function to directly initiate an OAuth login flow. It's a lower-level utility that is internally used by other parts of the library.
+
+**Parameters (`options`)**
+
+<x-field-group>
+  <x-field data-name="provider" data-type="string" data-required="true" data-desc="The OAuth provider to use, e.g., 'github', 'google'."></x-field>
+  <x-field data-name="action" data-type="string" data-required="true" data-desc="The action, typically 'login'."></x-field>
+  <x-field data-name="extraParams" data-type="object" data-required="false" data-desc="Additional parameters for the OAuth flow."></x-field>
+  <x-field data-name="onLogin" data-type="function" data-required="true" data-desc="Callback function executed upon successful login."></x-field>
+</x-field-group>

package/docs/hooks-use-connect.zh-TW.md

@@ -0,0 +1,214 @@
+# useConnect
+
+`useConnect` hook 提供了一種強大的程式化方式來開啟、關閉和管理 `DidConnect` UI 模態框。當您需要比宣告式 `Button` 元件提供更多對連線流程的控制時，例如從自訂 UI 元素、選單項目或響應應用程式事件來觸發模態框，這便是理想的解決方案。
+
+這個 hook 是 `Button` 元件背後的引擎，讓您可以直接存取相同的核心功能。
+
+## 運作方式
+
+`useConnect` hook 回傳兩個主要元素：
+
+1.  **`connectHolder`**：一個必須在您的元件樹中渲染的 React 元素。此元素負責在 `DidConnect` 模態框被啟動時進行渲染。在 `open` 函式被呼叫前，它保持不可見。
+2.  **`connectApi`**：一個包含您將用來控制模態框生命週期的函式（`open`、`close`、`openPopup`、`loginOAuth`）的物件。
+
+```d2
+direction: down
+
+User: { 
+  shape: c4-person 
+}
+
+Your-App: {
+  label: "您的應用程式"
+  shape: rectangle
+
+  Custom-Button: {
+    label: "自訂按鈕"
+  }
+
+  useConnect-Hook: {
+    label: "useConnect()"
+  }
+  
+  connectHolder: {
+    label: "connectHolder"
+  }
+}
+
+DID-Wallet: {
+  label: "DID Wallet"
+  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
+}
+
+User -> Your-App.Custom-Button: "1. 點擊"
+Your-App.Custom-Button -> Your-App.useConnect-Hook: "2. 呼叫 connectApi.open()"
+Your-App.useConnect-Hook -> Your-App.connectHolder: "3. 啟動模態框"
+Your-App.connectHolder -> User: "4. 顯示 DidConnect UI"
+User -> DID-Wallet: "5. 掃描 QR 並批准"
+DID-Wallet -> Your-App.connectHolder: "6. 發送回應"
+Your-App.connectHolder -> Your-App.useConnect-Hook: "7. 觸發 onSuccess 回呼"
+Your-App.useConnect-Hook -> Your-App.connectHolder: "8. 關閉模態框"
+
+```
+
+## 設定
+
+若要使用此 hook，請在您的元件中匯入並呼叫它。然後，確保您在應用程式的某處渲染 `connectHolder`，最好是在頂層元件中，以確保模態框可以覆蓋所有其他內容。
+
+```javascript Basic Setup icon=logos:javascript
+import React from 'react';
+import { useConnect } from '@arcblock/did-connect-react';
+
+function MyComponent() {
+  // 1. 初始化 hook
+  const { connectHolder, connectApi } = useConnect();
+
+  const handleLogin = () => {
+    // 2. 使用 API 開啟模態框
+    connectApi.open({
+      action: 'login',
+      onSuccess: (result) => {
+        console.log('登入成功！', result);
+      },
+      onClose: () => {
+        console.log('模態框已由使用者關閉。');
+      }
+    });
+  };
+
+  return (
+    <div>
+      <button type="button" onClick={handleLogin}>
+        使用 DID 登入
+      </button>
+
+      {/* 3. 渲染 holder 元件 */}
+      {connectHolder}
+    </div>
+  );
+}
+
+export default MyComponent;
+```
+
+## API 參考
+
+`connectApi` 物件提供以下方法來控制連線過程。
+
+### `connectApi.open(options)`
+
+這是觸發並顯示 `DidConnect` 模態框的主要函式。它接受一個 `options` 物件來設定連線會話的行為、外觀和回呼。
+
+**參數 (`options`)**
+
+<x-field-group>
+  <x-field data-name="action" data-type="string" data-required="true">
+    <x-field-desc markdown>連線請求的目的，例如 `login`、`claim`、`sign` 等。這決定了錢包內的工作流程。</x-field-desc>
+  </x-field>
+  <x-field data-name="onSuccess" data-type="(result: object) => void" data-required="false">
+    <x-field-desc markdown>當使用者在錢包中成功完成操作時執行的回呼函式。`result` 物件包含來自錢包的回應。</x-field-desc>
+  </x-field>
+  <x-field data-name="onClose" data-type="() => void" data-required="false">
+    <x-field-desc markdown>當使用者在未完成操作的情況下手動關閉模態框時執行的回呼函式。</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="(error: any) => void" data-required="false">
+    <x-field-desc markdown>如果在過程中發生錯誤（例如超時或網路問題）時執行的回呼函式。</x-field-desc>
+  </x-field>
+  <x-field data-name="messages" data-type="ConnectMessages" data-required="false">
+    <x-field-desc markdown>用於自訂模態框中顯示文字的物件。詳情請參閱 `ConnectMessages` 型別。</x-field-desc>
+    <x-field data-name="title" data-type="string" data-desc="模態框標題。"></x-field>
+    <x-field data-name="scan" data-type="string" data-desc="QR code 旁的文字。"></x-field>
+    <x-field data-name="confirm" data-type="string" data-desc="確認步驟的文字。"></x-field>
+    <x-field data-name="success" data-type="ReactNode" data-desc="成功畫面的內容。"></x-field>
+  </x-field>
+  <x-field data-name="popup" data-type="boolean" data-default="true">
+    <x-field-desc markdown>若為 `true`，UI 將以模態對話框形式顯示。若為 `false`，則會內聯渲染，需要設定 `containerEl`。</x-field-desc>
+  </x-field>
+  <x-field data-name="containerEl" data-type="Element" data-required="false">
+    <x-field-desc markdown>當 `popup` 設為 `false` 時，`DidConnect` 元件將在此 DOM 元素中渲染。</x-field-desc>
+  </x-field>
+  <x-field data-name="closeTimeout" data-type="number" data-default="2000">
+    <x-field-desc markdown>連線成功後，模態框自動關閉前的延遲時間（毫秒）。</x-field-desc>
+  </x-field>
+  <x-field data-name="checkInterval" data-type="number" data-default="2000">
+    <x-field-desc markdown>輪詢伺服器以檢查會話狀態的間隔時間（毫秒）。</x-field-desc>
+  </x-field>
+  <x-field data-name="checkTimeout" data-type="number" data-default="300000">
+    <x-field-desc markdown>連線嘗試超時前的總時間（毫秒）。</x-field-desc>
+  </x-field>
+  <x-field data-name="extraParams" data-type="object" data-default="{}">
+    <x-field-desc markdown>要包含在會話建立請求中的任何額外參數，這些參數可以在伺服器端擷取。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### `connectApi.close()`
+
+手動關閉 `DidConnect` 模態框。模態框在成功或使用者取消時會自動關閉，但如果您因其他原因需要以程式化方式關閉它，可以呼叫此函式。
+
+```javascript icon=lucide:x-circle
+// 範例：在成功回呼中短暫延遲後關閉模態框
+connectApi.open({
+  action: 'login',
+  onSuccess: () => {
+    showTemporarySuccessMessage();
+    setTimeout(() => {
+      connectApi.close();
+    }, 1500);
+  },
+  closeTimeout: 999999 // 防止自動關閉
+});
+```
+
+### `connectApi.openPopup(params, options)`
+
+此函式提供了一種替代的連線方法，它會在新的瀏覽器彈出視窗中開啟 DID Connect 流程，而不是在當前頁面內的模態框中。這對於某些類似 OAuth 的流程或與無法注入模態框的網站整合時非常有用。
+
+**參數**
+
+<x-field-group>
+  <x-field data-name="params" data-type="ConnectProps" data-required="true">
+    <x-field-desc markdown>與 `open` 方法的選項類似。一個關鍵區別是 `params.extraParams.provider` 是**必需的**，用於識別驗證方法（例如 'github'、'google'）。</x-field-desc>
+  </x-field>
+  <x-field data-name="options" data-type="object" data-required="false">
+    <x-field-desc markdown>彈出視窗本身的設定。</x-field-desc>
+    <x-field data-name="baseUrl" data-type="string" data-desc="用於建構彈出視窗 URL 的基礎 URL。"></x-field>
+    <x-field data-name="locale" data-type="string" data-default="en" data-desc="彈出視窗內容的語系。"></x-field>
+    <x-field data-name="popupOptions" data-type="object" data-desc="直接傳遞給 `window.open()` 的選項，用於自訂彈出視窗的大小和功能。"></x-field>
+  </x-field>
+</x-field-group>
+
+**用法**
+
+`openPopup` 函式回傳一個 `Promise`，在成功時會解析並帶有驗證資料，在失敗或取消時則會拒絕。
+
+```javascript icon=lucide:external-link
+const handleGithubLogin = async () => {
+  try {
+    const result = await connectApi.openPopup({
+      action: 'login',
+      onSuccess: () => console.log('此回呼也會被觸發'),
+      extraParams: { provider: 'github' } // 此為必需項
+    });
+    console.log('透過彈出視窗登入成功：', result);
+  } catch (err) {
+    if (err.message === 'Popup closed') {
+      console.log('使用者已關閉彈出視窗。');
+    } else {
+      console.error('發生錯誤：', err);
+    }
+  }
+};
+```
+
+### `connectApi.loginOAuth(options)`
+
+這是一個輔助函式，用於直接啟動 OAuth 登入流程。它是一個較低層級的工具，由函式庫的其他部分在內部使用。
+
+**參數 (`options`)**
+
+<x-field-group>
+  <x-field data-name="provider" data-type="string" data-required="true" data-desc="要使用的 OAuth 提供者，例如 'github'、'google'。"></x-field>
+  <x-field data-name="action" data-type="string" data-required="true" data-desc="操作，通常是 'login'。"></x-field>
+  <x-field data-name="extraParams" data-type="object" data-required="false" data-desc="OAuth 流程的額外參數。"></x-field>
+  <x-field data-name="onLogin" data-type="function" data-required="true" data-desc="登入成功後執行的回呼函式。"></x-field>
+</x-field-group>