@blocklet/payment-react 1.20.16 → 1.20.17

package/docs/components-checkout-checkout-donate.ja.md

@@ -0,0 +1,259 @@
+# CheckoutDonate
+
+`CheckoutDonate`コンポーネントは、アプリケーションに寄付機能を追加するための、柔軟で統合しやすいソリューションを提供します。チェックアウトダイアログを開くシンプルなボタンから、完全に制御可能なカスタムUIまで、さまざまな表示モードをサポートしています。
+
+このコンポーネントが正しく機能するためには、`PaymentProvider`と`DonateProvider`の両方でラップする必要があります。`DonateProvider`は、アプリケーションの特定のスコープ内における寄付インスタンスの設定と状態を管理します。
+
+## 仕組み
+
+寄付のフローは`DonateProvider`と`CheckoutDonate`の組み合わせによって調整されます。以下にその概要を示します。
+
+```d2 How It Works icon=graph-ql:diagram
+direction: down
+
+user: {
+  shape: c4-person
+}
+
+app: {
+  label: "あなたのReactアプリ"
+  
+  checkout-donate: {
+    label: "CheckoutDonate"
+  }
+  
+  checkout-form: {
+    label: "CheckoutForm (ダイアログ内)"
+  }
+}
+
+payment-api: {
+  label: "決済バックエンドAPI"
+  shape: cylinder
+}
+
+# Initial Load
+app.checkout-donate -> payment-api: "設定と支援者を取得"
+
+# Donation Flow
+user -> app.checkout-donate: "1. 寄付をクリック"
+app.checkout-donate -> app.checkout-form: "2. CheckoutFormを含むダイアログを開く"
+app.checkout-form -> payment-api: "3. 支払いを処理"
+payment-api -> app.checkout-form: "4. 成功を返す"
+app.checkout-form -> app.checkout-donate: "5. onPaidコールバックをトリガー"
+app.checkout-donate -> payment-api: "6. 支援者リストを再取得"
+payment-api -> app.checkout-donate: "7. 更新された支援者を返す"
+```
+
+1.  **初期化**：`DonateProvider`は、一意の`mountLocation`によって識別されるバックエンドから、寄付設定（プリセット金額、ボタンテキストなど）を取得してキャッシュします。
+2.  **レンダリング**：`CheckoutDonate`は、取得した設定と自身のpropsに基づいて、ボタンまたはカスタムUIをレンダリングします。
+3.  **インタラクション**：ユーザーが寄付を開始すると、`CheckoutDonate`は寄付用に事前設定された`CheckoutForm`を含むダイアログを開きます。
+4.  **支払い**：ユーザーは`CheckoutForm`を通じて支払いを完了します。
+5.  **確認**：支払いが成功すると、`onPaid`コールバックがトリガーされ、コンポーネントは自動的に支援者リストを更新します。
+
+## Providerのセットアップ
+
+`CheckoutDonate`を使用する前に、コンポーネントツリーを`PaymentProvider`と`DonateProvider`でラップする必要があります。
+
+```tsx Provider Setup Example icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // あなたのセッションコンテキストフック
+
+function DonationPage() {
+  const { session, connect } = useSessionContext();
+
+  // プロバイダーをレンダリングする前にセッションがロードされていることを確認
+  if (!session) {
+    return <div>読み込み中...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="unique-page-identifier" // この寄付コンテキストのための一意のキー
+        description="私の素晴らしいブログ投稿への寄付"
+        defaultSettings={{
+          btnText: '私を支援する',
+        }}>
+        {/* ここにCheckoutDonateコンポーネントを配置します */}
+        <CheckoutDonate 
+          settings={{
+            target: "post-123",
+            title: "著者を支援",
+            description: "この記事が役に立ったと思ったら、ぜひコーヒーを一杯おごってください",
+            reference: "https://your-site.com/posts/123",
+            beneficiaries: [
+              {
+                address: "z2qa...",
+                share: "100",
+              },
+            ],
+          }}
+        />
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+詳細は[`DonateProvider`](./providers-donate-provider.md)のドキュメントを参照してください。
+
+## コンポーネントのProps
+
+### `DonateProps`
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `settings` | `CheckoutDonateSettings` | **必須。** この特定の寄付インスタンスの設定。 |
+| `onPaid` | `(session) => void` | 任意。支払いが成功した後に実行されるコールバック関数。 |
+| `onError` | `(error) => void` | 任意。エラーが発生した場合に実行されるコールバック関数。 |
+| `mode` | `'default' \| 'inline' \| 'custom'` | 任意。レンダリングモード。デフォルトは`'default'`です。 |
+| `livemode` | `boolean` | 任意。`PaymentProvider`からの`livemode`を上書きします。 |
+| `timeout` | `number` | 任意。支払い後にダイアログを閉じるまでの待機時間（ミリ秒）。デフォルトは`5000`です。 |
+| `theme` | `'default' \| 'inherit' \| object` | 任意。テーマのカスタマイズオプション。[テーマ設定](./guides-theming.md)ガイドを参照してください。 |
+| `children` | `(openDialog, donateTotalAmount, supporters, loading, donateSettings) => React.ReactNode` | 任意。`mode="custom"`の場合にのみ使用されるレンダープロップ関数。 |
+
+### `CheckoutDonateSettings`
+
+このオブジェクトは`settings` propに渡され、寄付の核心的な詳細を定義します。
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `target` | `string` | **必須。** 寄付対象の一意の識別子（例：投稿ID、プロジェクト名）。 |
+| `title` | `string` | **必須。** 寄付ダイアログの上部に表示されるタイトル。 |
+| `description` | `string` | **必須。** 寄付ダイアログに表示される短い説明。 |
+| `reference` | `string` | **必須。** 参照用として使用される、寄付に関連するURL。 |
+| `beneficiaries` | `PaymentBeneficiary[]` | **必須。** 資金を受け取る人を定義するオブジェクトの配列。各オブジェクトには`address`（受取人のDID）と`share`（パーセンテージ）が必要です。 |
+| `amount` | `object` | 任意。寄付金額を設定します。`presets`（例：`['1', '5', '10']`）、デフォルトの`preset`、`minimum`、`maximum`、および`custom`金額が許可されるかどうかを含みます。 |
+| `appearance` | `object` | 任意。`button`（テキスト、アイコン、バリアント）や`history`の表示（`'avatar'`または`'table'`）を含む、ルックアンドフィールをカスタマイズします。 |
+
+## 使用例
+
+### デフォルトモード
+
+これは`CheckoutDonate`を使用する最も簡単な方法です。寄付ダイアログを開くボタンと、最近の支援者の概要をレンダリングします。
+
+```tsx Default Donation Button icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context';
+
+function App() {
+  const { session, connect } = useSessionContext();
+
+  if (!session) {
+    return <div>セッションを読み込み中...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="blog-post-123"
+        description="ブログ投稿123への寄付"
+        defaultSettings={{
+          btnText: 'コーヒーをおごる',
+          historyType: 'avatar',
+        }}>
+        <CheckoutDonate
+          settings={{
+            target: 'post-123',
+            title: '著者を支援',
+            description: 'この記事が役に立ったと思ったら、少額の寄付をご検討ください。',
+            reference: 'https://example.com/posts/123',
+            beneficiaries: [
+              {
+                address: 'z2qa...gCLd', // 著者のDIDアドレス
+                share: '100',
+              },
+            ],
+          }}
+          onPaid={() => {
+            console.log('寄付が成功しました！');
+          }}
+        />
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+### カスタムUIモード
+
+ユーザーインターフェースを完全に制御するには、`mode="custom"`を使用し、`children`としてレンダープロップを提供します。この関数は、集まった総額や支援者リストを含む寄付の状態へのアクセスを提供し、完全にカスタムな表示を構築することができます。
+
+```tsx Custom Donation UI icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context';
+import { CircularProgress, Button } from '@mui/material';
+
+function CustomDonationDisplay() {
+  const { session, connect } = useSessionContext();
+
+  if (!session) {
+    return <div>セッションを読み込み中...</div>;
+  }
+
+  const donateSettings = {
+    target: 'post-123',
+    title: '著者を支援',
+    description: 'この記事が役に立ったと思ったら、少額の寄付をご検討ください。',
+    reference: 'https://example.com/posts/123',
+    beneficiaries: [
+      {
+        address: 'z2qa...gCLd', // 著者のDIDアドレス
+        share: '100',
+      },
+    ],
+  };
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="blog-post-123"
+        description="ブログ投稿123への寄付">
+        <CheckoutDonate mode="custom" settings={donateSettings}>
+          {(openDonate, totalAmount, supporters, loading, settings) => (
+            <div style={{ border: '1px solid #ccc', padding: '16px', borderRadius: '8px' }}>
+              <h2>私たちの支援者</h2>
+              <p>寄付総額：<strong>{totalAmount}</strong></p>
+              <Button variant="contained" onClick={openDonate}>
+                {settings?.appearance?.button?.text || '今すぐ寄付'}
+              </Button>
+              {loading ? (
+                <CircularProgress style={{ marginTop: '16px' }} />
+              ) : (
+                <ul style={{ listStyle: 'none', padding: 0, marginTop: '16px' }}>
+                  {(supporters.supporters || []).map((supporter) => (
+                    <li key={supporter.id}>
+                      <span>{supporter.customer?.name}</span>
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </div>
+          )}
+        </CheckoutDonate>
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+`children`関数は、以下の引数を受け取ります：
+
+-   `openDonate`：手動で寄付ダイアログをトリガーする関数。
+-   `totalAmount`：寄付された総額のフォーマット済み文字列（例：`"125.00 T"`）。
+-   `supporters`：`supporters`配列と通貨情報を含む`DonateHistory`オブジェクト。
+-   `loading`：支援者データが取得中かどうかを示すブール値。
+-   `settings`：`DonateProvider`とpropsからマージされた、解決済みの寄付設定。

package/docs/components-checkout-checkout-donate.zh-TW.md

@@ -0,0 +1,259 @@
+# CheckoutDonate
+
+`CheckoutDonate` 元件提供了一個彈性且易於整合的解決方案，可為您的應用程式增加捐贈功能。它支援多種顯示模式，從開啟結帳對話方塊的簡單按鈕到由您完全控制的自訂 UI。
+
+此元件必須同時被 `PaymentProvider` 和 `DonateProvider` 包裹才能正常運作。`DonateProvider` 負責管理應用程式特定範圍內捐贈實例的設定和狀態。
+
+## 運作方式
+
+捐贈流程由 `DonateProvider` 和 `CheckoutDonate` 共同協調。以下是高層次的概述：
+
+```d2 How It Works icon=graph-ql:diagram
+direction: down
+
+user: {
+  shape: c4-person
+}
+
+app: {
+  label: "您的 React 應用程式"
+  
+  checkout-donate: {
+    label: "CheckoutDonate"
+  }
+  
+  checkout-form: {
+    label: "CheckoutForm (在對話方塊中)"
+  }
+}
+
+payment-api: {
+  label: "支付後端 API"
+  shape: cylinder
+}
+
+# 初始載入
+app.checkout-donate -> payment-api: "獲取設定和支持者"
+
+# 捐贈流程
+user -> app.checkout-donate: "1. 點擊捐贈"
+app.checkout-donate -> app.checkout-form: "2. 開啟帶有 CheckoutForm 的對話方塊"
+app.checkout-form -> payment-api: "3. 處理支付"
+payment-api -> app.checkout-form: "4. 回傳成功"
+app.checkout-form -> app.checkout-donate: "5. 觸發 onPaid 回呼"
+app.checkout-donate -> payment-api: "6. 重新獲取支持者列表"
+payment-api -> app.checkout-donate: "7. 回傳更新後的支持者"
+```
+
+1.  **初始化**：`DonateProvider` 從後端獲取並快取捐贈設定（如預設金額、按鈕文字），並透過唯一的 `mountLocation` 進行識別。
+2.  **渲染**：`CheckoutDonate` 根據檢索到的設定及其 props 渲染按鈕或自訂 UI。
+3.  **互動**：當使用者發起捐贈時，`CheckoutDonate` 會開啟一個包含為該捐贈預先設定好的 `CheckoutForm` 的對話方塊。
+4.  **支付**：使用者透過 `CheckoutForm` 完成支付。
+5.  **確認**：成功支付後，會觸發 `onPaid` 回呼，且元件會自動刷新支持者列表。
+
+## Provider 設定
+
+在使用 `CheckoutDonate` 之前，您必須用 `PaymentProvider` 和 `DonateProvider` 包裹您的元件樹。
+
+```tsx Provider Setup Example icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // 您的 session context hook
+
+function DonationPage() {
+  const { session, connect } = useSessionContext();
+
+  // 確保在渲染 provider 之前載入 session
+  if (!session) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="unique-page-identifier" // 此捐贈情境的唯一金鑰
+        description="給我很棒的部落格文章的捐贈"
+        defaultSettings={{
+          btnText: '支持我',
+        }}>
+        {/* 您的 CheckoutDonate 元件放在這裡 */}
+        <CheckoutDonate 
+          settings={{
+            target: "post-123",
+            title: "支持作者",
+            description: "如果您覺得這篇文章有幫助，歡迎請我喝杯咖啡",
+            reference: "https://your-site.com/posts/123",
+            beneficiaries: [
+              {
+                address: "z2qa...",
+                share: "100",
+              },
+            ],
+          }}
+        />
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+更多詳情，請參閱 [`DonateProvider`](./providers-donate-provider.md) 文件。
+
+## 元件 Props
+
+### `DonateProps`
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `settings` | `CheckoutDonateSettings` | **必填。** 此特定捐贈實例的設定。 |
+| `onPaid` | `(session) => void` | 選填。成功支付後執行的回呼函式。 |
+| `onError` | `(error) => void` | 選填。發生錯誤時執行的回呼函式。 |
+| `mode` | `'default' \| 'inline' \| 'custom'` | 選填。渲染模式。預設為 `'default'`。 |
+| `livemode` | `boolean` | 選填。覆寫來自 `PaymentProvider` 的 `livemode`。 |
+| `timeout` | `number` | 選填。支付後關閉對話方塊前等待的毫秒數。預設為 `5000`。 |
+| `theme` | `'default' \| 'inherit' \| object` | 選填。主題自訂選項。請參閱 [主題設定](./guides-theming.md) 指南。 |
+| `children` | `(openDialog, donateTotalAmount, supporters, loading, donateSettings) => React.ReactNode` | 選填。僅在 `mode="custom"` 時使用的 render prop 函式。 |
+
+### `CheckoutDonateSettings`
+
+此物件被傳遞給 `settings` prop，並定義了捐贈的核心細節。
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `target` | `string` | **必填。** 捐贈目標的唯一識別碼（例如，文章 ID、專案名稱）。 |
+| `title` | `string` | **必填。** 顯示在捐贈對話方塊頂部的標題。 |
+| `description` | `string` | **必填。** 顯示在捐贈對話方塊中的簡短描述。 |
+| `reference` | `string` | **必填。** 與捐贈相關的 URL，用於參考。 |
+| `beneficiaries` | `PaymentBeneficiary[]` | **必填。** 一個物件陣列，定義資金接收者。每個物件都需要 `address`（收款人的 DID）和 `share`（百分比）。 |
+| `amount` | `object` | 選填。設定捐贈金額，包括 `presets`（例如 `['1', '5', '10']`）、預設的 `preset`、`minimum`、`maximum` 以及是否允許 `custom` 金額。 |
+| `appearance` | `object` | 選填。自訂外觀和風格，包括 `button`（文字、圖示、樣式）和 `history` 顯示（`'avatar'` 或 `'table'`）。 |
+
+## 使用範例
+
+### 預設模式
+
+這是使用 `CheckoutDonate` 最簡單的方式。它會渲染一個按鈕，該按鈕會開啟一個捐贈對話方塊，並附上近期支持者的摘要。
+
+```tsx Default Donation Button icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context';
+
+function App() {
+  const { session, connect } = useSessionContext();
+
+  if (!session) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="blog-post-123"
+        description="給部落格文章 123 的捐贈"
+        defaultSettings={{
+          btnText: '請我喝杯咖啡',
+          historyType: 'avatar',
+        }}>
+        <CheckoutDonate
+          settings={{
+            target: 'post-123',
+            title: '支持作者',
+            description: '如果您覺得這篇文章有幫助，請考慮小額捐款。',
+            reference: 'https://example.com/posts/123',
+            beneficiaries: [
+              {
+                address: 'z2qa...gCLd', // 作者的 DID 地址
+                share: '100',
+              },
+            ],
+          }}
+          onPaid={() => {
+            console.log('捐贈成功！');
+          }}
+        />
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+### 自訂 UI 模式
+
+若要完全控制使用者介面，請使用 `mode="custom"` 並提供一個 render prop 作為 `children`。此函式讓您能存取捐贈狀態，包括募集的總金額和支持者列表，從而讓您能夠建立完全自訂的顯示方式。
+
+```tsx Custom Donation UI icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context';
+import { CircularProgress, Button } from '@mui/material';
+
+function CustomDonationDisplay() {
+  const { session, connect } = useSessionContext();
+
+  if (!session) {
+    return <div>Loading session...</div>;
+  }
+
+  const donateSettings = {
+    target: 'post-123',
+    title: '支持作者',
+    description: '如果您覺得這篇文章有幫助，請考慮小額捐款。',
+    reference: 'https://example.com/posts/123',
+    beneficiaries: [
+      {
+        address: 'z2qa...gCLd', // 作者的 DID 地址
+        share: '100',
+      },
+    ],
+  };
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="blog-post-123"
+        description="給部落格文章 123 的捐贈">
+        <CheckoutDonate mode="custom" settings={donateSettings}>
+          {(openDonate, totalAmount, supporters, loading, settings) => (
+            <div style={{ border: '1px solid #ccc', padding: '16px', borderRadius: '8px' }}>
+              <h2>我們的支持者</h2>
+              <p>總捐贈金額：<strong>{totalAmount}</strong></p>
+              <Button variant="contained" onClick={openDonate}>
+                {settings?.appearance?.button?.text || '立即捐贈'}
+              </Button>
+              {loading ? (
+                <CircularProgress style={{ marginTop: '16px' }} />
+              ) : (
+                <ul style={{ listStyle: 'none', padding: 0, marginTop: '16px' }}>
+                  {(supporters.supporters || []).map((supporter) => (
+                    <li key={supporter.id}>
+                      <span>{supporter.customer?.name}</span>
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </div>
+          )}
+        </CheckoutDonate>
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+`children` 函式會收到以下參數：
+
+-   `openDonate`：一個手動觸發捐贈對話方塊的函式。
+-   `totalAmount`：已捐贈總金額的格式化字串（例如 `"125.00 T"`）。
+-   `supporters`：一個 `DonateHistory` 物件，包含 `supporters` 陣列和貨幣資訊。
+-   `loading`：一個布林值，表示是否正在獲取支持者資料。
+-   `settings`：已解析的捐贈設定，由 `DonateProvider` 和 props 合併而成。