# useConnect

`useConnect`フックは、`DidConnect` UIモーダルをプログラムで開閉・管理するための強力な方法を提供します。宣言的な`Button`コンポーネントが提供するものよりも接続フローをより詳細に制御する必要がある場合、例えばカスタムUI要素、メニュー項目、またはアプリケーションイベントに応じてモーダルをトリガーする場合に理想的なソリューションです。

このフックは`Button`コンポーネントの背後にあるエンジンであり、同じコア機能への直接アクセスを提供します。

## 仕組み

`useConnect`フックは、主に2つの要素を返します：

1.  **`connectHolder`**：コンポーネントツリーにレンダリングする必要があるReact要素です。この要素は、`DidConnect`モーダルがアクティブ化されたときにそれをレンダリングする責任があります。`open`関数が呼び出されるまで非表示のままです。
2.  **`connectApi`**：モーダルのライフサイクルを制御するために使用する関数（`open`、`close`、`openPopup`、`loginOAuth`）を含むオブジェクトです。

<!-- DIAGRAM_IMAGE_START:flowchart:4:3:1765962229 -->
![useConnect](assets/diagram/use-connect-diagram-0.ja.jpg)
<!-- DIAGRAM_IMAGE_END -->

## セットアップ

フックを使用するには、それをインポートし、コンポーネント内で呼び出します。次に、アプリケーションのどこか、できればトップレベルのコンポーネントで`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>