@blocklet/payment-react 1.20.16 → 1.20.17

package/docs/components-checkout.ja.md

@@ -0,0 +1,65 @@
+# チェックアウトコンポーネント
+
+`@blocklet/payment-react` ライブラリは、さまざまな支払いシナリオに対応する、すぐに使える完全なエントリーポイントとして設計された、高レベルのチェックアウトコンポーネントのセットを提供します。これらのコンポーネントは、製品の選択から支払いの完了まで、ユーザーフロー全体をカプセル化しており、最小限の設定で複雑な支払い体験を統合できます。
+
+価格表の表示、寄付の受付、または直接支払いリンクの処理が必要な場合でも、これらのコンポーネントはセッション作成、状態管理、UIレンダリングの基盤となるロジックを処理します。
+
+### コンポーネントフロー
+
+一般的なフローでは、ユーザーが `CheckoutTable` や `CheckoutDonate` のようなエントリーポイントコンポーネントと対話します。これらのコンポーネントは `CheckoutSession` を作成し、最終的な支払い処理をコアの `CheckoutForm` コンポーネントに委任します。
+
+```d2 チェックアウトコンポーネントフロー icon=mdi:transit-connection-variant
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Checkout-Flow: {
+  label: "チェックアウトフロー"
+
+  Entry-Points: {
+    label: "ユーザー向けコンポーネント"
+    shape: rectangle
+
+    CheckoutTable: {
+      label: "CheckoutTable"
+    }
+
+    CheckoutDonate: {
+      label: "CheckoutDonate"
+    }
+  }
+
+  Core-Processor: {
+    label: "コア決済プロセッサー"
+    shape: rectangle
+
+    CheckoutForm: {
+      label: "CheckoutForm"
+    }
+  }
+}
+
+User -> Checkout-Flow.Entry-Points.CheckoutTable: "サブスクリプションを選択"
+User -> Checkout-Flow.Entry-Points.CheckoutDonate: "寄付を行う"
+Checkout-Flow.Entry-Points.CheckoutTable -> Checkout-Flow.Core-Processor.CheckoutForm: "プラン選択時"
+Checkout-Flow.Entry-Points.CheckoutDonate -> Checkout-Flow.Core-Processor.CheckoutForm: "寄付アクション時"
+Checkout-Flow.Core-Processor.CheckoutForm -> User: "支払い結果"
+```
+
+以下のコンポーネントを調べて、アプリケーションのニーズに最適なものを見つけてください。
+
+<x-cards data-columns="3">
+  <x-card data-title="CheckoutForm" data-icon="lucide:credit-card" data-href="/components/checkout/checkout-form">
+    支払いを処理するための基本的なコンポーネントです。`paymentLink` または `checkoutSession` ID を受け取り、完全な支払いUIをレンダリングします。
+  </x-card>
+  <x-card data-title="CheckoutTable" data-icon="lucide:table" data-href="/components/checkout/checkout-table">
+    完全な価格表を表示します。ユーザーがプランを選択すると、自動的にチェックアウトセッションを開始し、支払いフォームをレンダリングします。
+  </x-card>
+  <x-card data-title="CheckoutDonate" data-icon="lucide:heart-handshake" data-href="/components/checkout/checkout-donate">
+    寄付機能を追加するための柔軟なコンポーネントです。寄付の設定、サポーター履歴の表示、寄付の支払いフローを管理します。
+  </x-card>
+</x-cards>
+
+これらの各コンポーネントは、高度にカスタマイズ可能であり、アプリケーションにシームレスに統合できるように設計されています。いずれかのカードをクリックして、詳細なドキュメントと使用例をご覧ください。

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

@@ -0,0 +1,65 @@
+# 結帳元件
+
+`@blocklet/payment-react` 函式庫提供了一組高階的結帳元件，旨在為各種支付場景提供完整、即用的入口點。這些元件封裝了從選擇產品到完成支付的整個使用者流程，讓您能以最少的設定整合複雜的支付體驗。
+
+無論您需要顯示價格表、接受捐贈，還是處理直接支付連結，這些元件都能處理會話建立、狀態管理和 UI 渲染的底層邏輯。
+
+### 元件流程
+
+典型的流程是使用者與像 `CheckoutTable` 或 `CheckoutDonate` 這樣的入口點元件互動。這些元件接著會建立一個 `CheckoutSession`，並將最終的支付處理委託給核心的 `CheckoutForm` 元件。
+
+```d2 Checkout Component Flow icon=mdi:transit-connection-variant
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Checkout-Flow: {
+  label: "結帳流程"
+
+  Entry-Points: {
+    label: "面向使用者的元件"
+    shape: rectangle
+
+    CheckoutTable: {
+      label: "CheckoutTable"
+    }
+
+    CheckoutDonate: {
+      label: "CheckoutDonate"
+    }
+  }
+
+  Core-Processor: {
+    label: "核心支付處理器"
+    shape: rectangle
+
+    CheckoutForm: {
+      label: "CheckoutForm"
+    }
+  }
+}
+
+User -> Checkout-Flow.Entry-Points.CheckoutTable: "選擇一個訂閱"
+User -> Checkout-Flow.Entry-Points.CheckoutDonate: "進行捐贈"
+Checkout-Flow.Entry-Points.CheckoutTable -> Checkout-Flow.Core-Processor.CheckoutForm: "選擇方案時"
+Checkout-Flow.Entry-Points.CheckoutDonate -> Checkout-Flow.Core-Processor.CheckoutForm: "捐贈操作時"
+Checkout-Flow.Core-Processor.CheckoutForm -> User: "支付結果"
+```
+
+探索下方的元件，找到最適合您應用程式需求的選擇。
+
+<x-cards data-columns="3">
+  <x-card data-title="CheckoutForm" data-icon="lucide:credit-card" data-href="/components/checkout/checkout-form">
+    用於處理支付的基礎元件。它接受一個 `paymentLink` 或 `checkoutSession` ID，並渲染完整的支付 UI。
+  </x-card>
+  <x-card data-title="CheckoutTable" data-icon="lucide:table" data-href="/components/checkout/checkout-table">
+    顯示一個完整的價格表。當使用者選擇一個方案時，它會自動啟動一個結帳會話並渲染支付表單。
+  </x-card>
+  <x-card data-title="CheckoutDonate" data-icon="lucide:heart-handshake" data-href="/components/checkout/checkout-donate">
+    一個用於新增捐贈功能的彈性元件。它處理捐贈設定、顯示支持者歷史記錄，並管理捐贈支付流程。
+  </x-card>
+</x-cards>
+
+這些元件中的每一個都設計為高度可自訂，並且可以無縫整合到您的應用程式中。點擊任何卡片以查看其詳細文件和使用範例。

package/docs/components-checkout.zh.md

@@ -0,0 +1,65 @@
+# Checkout 组件
+
+`@blocklet/payment-react` 库提供了一套高级 Checkout 组件，旨在为各种支付场景提供完整、即用型的入口点。这些组件封装了从选择产品到完成支付的整个用户流程，让您能够以最少的设置集成复杂的支付体验。
+
+无论您需要显示定价表、接受捐赠，还是处理直接支付链接，这些组件都会处理会话创建、状态管理和 UI 渲染的底层逻辑。
+
+### 组件流程
+
+典型流程涉及用户与入口点组件（如 `CheckoutTable` 或 `CheckoutDonate`）进行交互。这些组件随后会创建一个 `CheckoutSession`，并将最终的支付处理委托给核心的 `CheckoutForm` 组件。
+
+```d2 Checkout Component Flow icon=mdi:transit-connection-variant
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Checkout-Flow: {
+  label: "Checkout Flow"
+
+  Entry-Points: {
+    label: "User-Facing Components"
+    shape: rectangle
+
+    CheckoutTable: {
+      label: "CheckoutTable"
+    }
+
+    CheckoutDonate: {
+      label: "CheckoutDonate"
+    }
+  }
+
+  Core-Processor: {
+    label: "Core Payment Processor"
+    shape: rectangle
+
+    CheckoutForm: {
+      label: "CheckoutForm"
+    }
+  }
+}
+
+User -> Checkout-Flow.Entry-Points.CheckoutTable: "Selects a subscription"
+User -> Checkout-Flow.Entry-Points.CheckoutDonate: "Makes a donation"
+Checkout-Flow.Entry-Points.CheckoutTable -> Checkout-Flow.Core-Processor.CheckoutForm: "On plan selection"
+Checkout-Flow.Entry-Points.CheckoutDonate -> Checkout-Flow.Core-Processor.CheckoutForm: "On donate action"
+Checkout-Flow.Core-Processor.CheckoutForm -> User: "Payment Result"
+```
+
+浏览以下组件，找到最适合您应用程序需求的组件。
+
+<x-cards data-columns="3">
+  <x-card data-title="CheckoutForm" data-icon="lucide:credit-card" data-href="/components/checkout/checkout-form">
+    处理支付的基础组件。它接收一个 `paymentLink` 或 `checkoutSession` ID，并渲染完整的支付 UI。
+  </x-card>
+  <x-card data-title="CheckoutTable" data-icon="lucide:table" data-href="/components/checkout/checkout-table">
+    显示一个完整的定价表。当用户选择一个方案时，它会自动启动一个结账会话并渲染支付表单。
+  </x-card>
+  <x-card data-title="CheckoutDonate" data-icon="lucide:heart-handshake" data-href="/components/checkout/checkout-donate">
+    一个用于添加捐赠功能的灵活组件。它负责处理捐赠设置、显示支持者历史记录以及管理捐赠支付流程。
+  </x-card>
+</x-cards>
+
+这些组件中的每一个都设计为高度可定制，并且可以无缝集成到您的应用程序中。单击任何卡片以查看其详细文档和使用示例。

package/docs/components-history-credit-grants-list.ja.md

@@ -0,0 +1,73 @@
+# CreditGrantsList
+
+`CreditGrantsList`コンポーネントは、顧客のクレジット付与を表示するページ分割されたテーブルを描画します。各付与のステータス、残高、範囲、および有効期間の明確な概要を提供します。
+
+このコンポーネントは、ユーザーが利用可能なクレジットを追跡できる顧客向けポータルと、顧客の付与を管理するための管理者ダッシュボードの両方にとって不可欠です。必要なセッションとAPIコンテキストにアクセスするには、`PaymentProvider`内で使用する必要があります。
+
+## Props
+
+| Prop | Type | Description | Default |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | オプション。顧客のID。省略した場合、セッションコンテキストから現在認証されているユーザーのDIDがデフォルトになります。 | `session.user.did` |
+| `subscription_id` | `string` | オプション。リストをフィルタリングして、特定のサブスクリプションに関連付けられた付与のみを表示します。 | `''` |
+| `status` | `string` | オプション。フィルタリングするステータスのカンマ区切り文字列。有効なステータスには、`granted`、`pending`、`expired`、`depleted`、および`voided`が含まれます。 | `'granted,pending,depleted,expired'` |
+| `pageSize` | `number` | オプション。ページごとに表示するアイテムの数。 | `10` |
+| `onTableDataChange` | `(data, prevData) => void` | オプション。テーブルデータが取得または更新されるたびに呼び出されるコールバック関数。 | `() => {}` |
+| `mode` | `'dashboard' \| 'portal'` | オプション。行がクリックされたときのナビゲーション動作を決定します。顧客向けのビューには `'portal'` を、管理者パネルには `'dashboard'` を使用します。これにより、異なるリンクパスが生成されます。 | `'portal'` |
+
+## 使用方法
+
+### 基本的な使用法（ログイン中の顧客向け）
+
+デフォルトでは、`CreditGrantsList`コンポーネントは現在認証されているユーザーのクレジット付与を取得して表示します。これは、顧客のアカウントページで最も一般的な使用例です。
+
+```jsx 私のクレジット付与 icon=logos:react
+import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '/path/to/your/session/context'; // このインポートパスを調整してください
+
+function MyCreditGrantsPage() {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>セッションを読み込み中...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h2>私のクレジット付与</h2>
+      <CreditGrantsList />
+    </PaymentProvider>
+  );
+}
+```
+
+### 管理者またはダッシュボードでの使用
+
+管理ダッシュボードでは、`customer_id` prop を提供することで、任意の顧客のクレジット付与を表示できます。フィルターやページサイズもカスタマイズできます。
+
+```jsx 顧客のクレジット付与 icon=logos:react
+import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '/path/to/your/session/context'; // このインポートパスを調整してください
+
+function CustomerDetailsPage({ customerId }) {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>セッションを読み込み中...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h3>顧客の有効なクレジット付与</h3>
+      <CreditGrantsList
+        customer_id={customerId}
+        status="granted,pending"
+        pageSize={5}
+        mode="dashboard"
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+この例では、特定の顧客に対して「granted」および「pending」の付与のみをリスト表示し、1ページあたり5項目を表示する方法を示しています。`mode="dashboard"`は、付与をクリックすると管理者専用のURLにナビゲートすることを保証します。

package/docs/components-history-credit-grants-list.zh-TW.md

@@ -0,0 +1,73 @@
+# CreditGrantsList
+
+`CreditGrantsList` 元件會渲染一個分頁表格，用來顯示客戶的信用額度授予。它清晰地概覽了每筆授予的狀態、剩餘額度、適用範圍和有效期限。
+
+這個元件對於客戶端入口網站（使用者可在此追蹤其可用信用額度）和管理員儀表板（用於管理客戶的授予）都至關重要。它必須在 `PaymentProvider` 中使用，才能存取必要的會話和 API 上下文。
+
+## 屬性
+
+| 屬性 | 類型 | 說明 | 預設值 |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | 可選。客戶的 ID。如果省略，則預設為目前已驗證使用者的 DID（來自會話上下文）。 | `session.user.did` |
+| `subscription_id` | `string` | 可選。篩選列表，僅顯示與特定訂閱相關的授予。 | `''` |
+| `status` | `string` | 可選。用逗號分隔的狀態字串，用於篩選。有效的狀態包括 `granted`、`pending`、`expired`、`depleted` 和 `voided`。 | `'granted,pending,depleted,expired'` |
+| `pageSize` | `number` | 可選。每頁顯示的項目數量。 | `10` |
+| `onTableDataChange` | `(data, prevData) => void` | 可選。一個回呼函式，每當表格資料被擷取或更新時都會被呼叫。 | `() => {}` |
+| `mode` | `'dashboard' \| 'portal'` | 可選。決定點擊某一行時的導航行為。為客戶端視圖使用 `'portal'`，為管理員面板使用 `'dashboard'`，這會產生不同的連結路徑。 | `'portal'` |
+
+## 使用方式
+
+### 基本用法（適用於已登入的客戶）
+
+預設情況下，`CreditGrantsList` 元件會擷取並顯示目前已驗證使用者的信用額度授予。這是客戶帳戶頁面最常見的使用情境。
+
+```jsx 我的信用額度授予 icon=logos:react
+import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '/path/to/your/session/context'; // 調整此導入路徑
+
+function MyCreditGrantsPage() {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>載入會話中...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h2>我的信用額度授予</h2>
+      <CreditGrantsList />
+    </PaymentProvider>
+  );
+}
+```
+
+### 管理員或儀表板用法
+
+在管理儀表板中，您可以透過提供 `customer_id` 屬性來顯示任何客戶的信用額度授予。您也可以自訂篩選器和頁面大小。
+
+```jsx 客戶信用額度授予 icon=logos:react
+import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '/path/to/your/session/context'; // 調整此導入路徑
+
+function CustomerDetailsPage({ customerId }) {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>載入會話中...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h3>客戶的有效信用額度授予</h3>
+      <CreditGrantsList
+        customer_id={customerId}
+        status="granted,pending"
+        pageSize={5}
+        mode="dashboard"
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+此範例展示了如何僅列出特定客戶的「granted」和「pending」授予，每頁顯示 5 個項目。`mode="dashboard"` 確保點擊某個授予後會導航至管理員專用的 URL。

package/docs/components-history-credit-grants-list.zh.md

@@ -0,0 +1,73 @@
+# CreditGrantsList
+
+`CreditGrantsList` 组件渲染一个分页表格，用于显示客户的信用额度授予情况。它清晰地概述了每笔授予的状态、剩余额度、范围和有效期。
+
+该组件对于面向客户的门户（用户可以在其中跟踪其可用信用额度）和用于管理客户授予的管理仪表板都至关重要。它必须在 `PaymentProvider` 内部使用，以访问必要的会话和 API 上下文。
+
+## Props
+
+| Prop | Type | Description | Default |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | 可选。客户的 ID。如果省略，则默认为会话上下文中当前已认证用户的 DID。 | `session.user.did` |
+| `subscription_id` | `string` | 可选。筛选列表，仅显示与特定订阅关联的授予。 | `''` |
+| `status` | `string` | 可选。一个用逗号分隔的状态字符串，用于筛选。有效状态包括 `granted`、`pending`、`expired`、`depleted` 和 `voided`。 | `'granted,pending,depleted,expired'` |
+| `pageSize` | `number` | 可选。每页显示的项目数。 | `10` |
+| `onTableDataChange` | `(data, prevData) => void` | 可选。每当获取或更新表格数据时调用的回调函数。 | `() => {}` |
+| `mode` | `'dashboard' \| 'portal'` | 可选。决定点击行时的导航行为。对面向客户的视图使用 `'portal'`，对管理面板使用 `'dashboard'`，这将生成不同的链接路径。 | `'portal'` |
+
+## 用法
+
+### 基本用法（针对已登录客户）
+
+默认情况下，`CreditGrantsList` 组件会获取并显示当前已认证用户的信用额度授予。这是客户账户页面最常见的用例。
+
+```jsx 我的信用额度授予 icon=logos:react
+import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '/path/to/your/session/context'; // 调整此导入路径
+
+function MyCreditGrantsPage() {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>正在加载会话...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h2>我的信用额度授予</h2>
+      <CreditGrantsList />
+    </PaymentProvider>
+  );
+}
+```
+
+### 管理员或仪表板用法
+
+在管理仪表板中，您可以通过提供 `customer_id` 属性来显示任何客户的信用额度授予。您还可以自定义筛选条件和页面大小。
+
+```jsx 客户的信用额度授予 icon=logos:react
+import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '/path/to/your/session/context'; // 调整此导入路径
+
+function CustomerDetailsPage({ customerId }) {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>正在加载会话...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h3>客户的有效信用额度授予</h3>
+      <CreditGrantsList
+        customer_id={customerId}
+        status="granted,pending"
+        pageSize={5}
+        mode="dashboard"
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+此示例展示了如何仅列出特定客户的 'granted' 和 'pending' 状态的授予，每页显示 5 项。`mode="dashboard"` 确保了点击某项授予将导航至管理员专用的 URL。

package/docs/components-history-credit-transactions-list.ja.md

@@ -0,0 +1,106 @@
+# CreditTransactionsList
+
+`CreditTransactionsList`コンポーネントは、すべてのクレジット取引の詳細なページ分割テーブルを描画し、クレジットの使用状況と調整の明確なログを提供します。顧客ポータルや管理ダッシュボードで、クレジットの付与と消費を追跡するのに最適です。
+
+このコンポーネントは、データの取得、ページネーション、フォーマットを自動的に処理し、取引履歴を簡単に表示する方法を提供します。
+
+## Props
+
+| Prop | Type | Description | Default |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | 取引を表示する顧客のID。指定しない場合は、`PaymentProvider`コンテキストから現在ログインしているユーザーのDIDがデフォルト値になります。 | `session.user.did` |
+| `subscription_id` | `string` | 取引を特定のサブスクリプションに絞り込みます。 | `undefined` |
+| `credit_grant_id` | `string` | 取引を特定のクレジット付与に絞り込みます。 | `undefined` |
+| `pageSize` | `number` | 1ページに表示する取引の数。 | `10` |
+| `onTableDataChange` | `(data, prevData) => void` | テーブルデータが取得または更新されたときにトリガーされるコールバック関数です。 | `() => {}` |
+| `showAdminColumns` | `boolean` | `true`で、かつユーザーが管理者の場合、「Meter Event」などの追加列が表示されます。 | `false` |
+| `showTimeFilter` | `boolean` | `true`の場合、日付範囲ピッカーが表示され、日付による取引の絞り込みが可能になります。 | `false` |
+| `source` | `string` | 取引を絞り込むためのオプションのソース文字列です。 | `''` |
+| `mode` | `'dashboard' \| 'portal'` | クレジット付与などの関連項目のリンク構造を決定します。管理者ビューには`'dashboard'`を、顧客向けビューには`'portal'`を使用します。 | `'portal'` |
+
+## 顧客ポータルの基本使用法
+
+この例では、現在ログインしているユーザーのクレジット取引履歴を表示する方法を示します。`customer_id`を省略すると、コンポーネントは`PaymentProvider`コンテキストからユーザーのDIDを自動的に使用します。
+
+```jsx MyCreditHistoryPage.tsx icon=logos:react
+import React from 'react';
+import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // セッションコンテキストのフック
+
+function MyCreditHistoryPage() {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>セッションを読み込んでいます...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h2>私のクレジット取引</h2>
+      <CreditTransactionsList />
+    </PaymentProvider>
+  );
+}
+
+export default MyCreditHistoryPage;
+```
+
+## フィルタリング付き管理者ビュー
+
+管理者ダッシュボードでは、特定の`customer_id`を渡し、管理者列と時間フィルターを有効にすることで、ユーザーの取引履歴をより強力かつ詳細に表示できます。
+
+```jsx CustomerDetailsPage.tsx icon=logos:react
+import React from 'react';
+import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // セッションコンテキストのフック
+
+function CustomerDetailsPage({ customerId }) {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>セッションを読み込んでいます...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h3>{customerId}の取引履歴</h3>
+      <CreditTransactionsList
+        customer_id={customerId}
+        showAdminColumns={true}
+        showTimeFilter={true}
+        pageSize={20}
+        mode="dashboard"
+      />
+    </PaymentProvider>
+  );
+}
+
+export default CustomerDetailsPage;
+```
+
+## 特定のクレジット付与の取引表示
+
+特定のクレジット付与がどのように消費されたかの詳細なログを表示するには、`credit_grant_id`を渡します。これは、単一のクレジット付与の詳細を表示するページで役立ちます。
+
+```jsx CreditGrantDetailsPage.tsx icon=logos:react
+import React from 'react';
+import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // セッションコンテキストのフック
+
+function CreditGrantDetailsPage({ grantId }) {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>セッションを読み込んでいます...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h4>付与{grantId}の使用詳細</h4>
+      <CreditTransactionsList credit_grant_id={grantId} />
+    </PaymentProvider>
+  );
+}
+
+export default CreditGrantDetailsPage;
+```

package/docs/components-history-credit-transactions-list.zh-TW.md

@@ -0,0 +1,106 @@
+# CreditTransactionsList
+
+`CreditTransactionsList` 元件會呈現一個詳細且分頁的所有點數交易表格，提供清晰的點數使用和調整記錄。它非常適合在客戶入口網站或管理儀表板中使用，以追蹤點數如何授予和消耗。
+
+此元件會自動處理資料擷取、分頁和格式化，提供一種直接顯示交易歷史記錄的方法。
+
+## 屬性
+
+| 屬性 | 類型 | 說明 | 預設值 |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | 要顯示其交易的客戶 ID。如果未提供，則預設為來自 `PaymentProvider` 上下文的當前登入使用者的 DID。 | `session.user.did` |
+| `subscription_id` | `string` | 將交易篩選至特定的訂閱。 | `undefined` |
+| `credit_grant_id` | `string` | 將交易篩選至特定的點數授予。 | `undefined` |
+| `pageSize` | `number` | 每頁顯示的交易數量。 | `10` |
+| `onTableDataChange` | `(data, prevData) => void` | 當表格資料被擷取或更新時觸發的回呼函式。 | `() => {}` |
+| `showAdminColumns` | `boolean` | 如果為 `true` 且使用者是管理員，則會顯示額外的欄位，例如「Meter Event」。 | `false` |
+| `showTimeFilter` | `boolean` | 如果為 `true`，則會顯示日期範圍選擇器，以允許按日期篩選交易。 | `false` |
+| `source` | `string` | 用於篩選交易的可選來源字串。 | `''` |
+| `mode` | `'dashboard' \| 'portal'` | 決定相關項目（如點數授予）的連結結構。使用 `'dashboard'` 表示管理員視圖，使用 `'portal'` 表示客戶導向的視圖。 | `'portal'` |
+
+## 客戶入口網站的基本用法
+
+此範例展示了如何顯示當前登入使用者的點數交易歷史記錄。當 `customer_id` 被省略時，該元件會自動從 `PaymentProvider` 上下文中使用使用者的 DID。
+
+```jsx MyCreditHistoryPage.tsx icon=logos:react
+import React from 'react';
+import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // 您的會話上下文鉤子
+
+function MyCreditHistoryPage() {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>正在載入會話...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h2>我的點數交易</h2>
+      <CreditTransactionsList />
+    </PaymentProvider>
+  );
+}
+
+export default MyCreditHistoryPage;
+```
+
+## 帶有篩選功能的管理員視圖
+
+對於管理員儀表板，您可以傳遞特定的 `customer_id` 並啟用管理員欄位和時間篩選器，以提供更強大、更詳細的使用者交易歷史記錄視圖。
+
+```jsx CustomerDetailsPage.tsx icon=logos:react
+import React from 'react';
+import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // 您的會話上下文鉤子
+
+function CustomerDetailsPage({ customerId }) {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>正在載入會話...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h3>{customerId} 的交易歷史記錄</h3>
+      <CreditTransactionsList
+        customer_id={customerId}
+        showAdminColumns={true}
+        showTimeFilter={true}
+        pageSize={20}
+        mode="dashboard"
+      />
+    </PaymentProvider>
+  );
+}
+
+export default CustomerDetailsPage;
+```
+
+## 顯示特定點數授予的交易
+
+若要顯示特定點數授予如何被消耗的詳細日誌，請傳遞 `credit_grant_id`。這對於顯示單個點數授予詳細資訊的頁面非常有用。
+
+```jsx CreditGrantDetailsPage.tsx icon=logos:react
+import React from 'react';
+import { CreditTransactionsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // 您的會話上下文鉤子
+
+function CreditGrantDetailsPage({ grantId }) {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>正在載入會話...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h4>授予 {grantId} 的使用詳情</h4>
+      <CreditTransactionsList credit_grant_id={grantId} />
+    </PaymentProvider>
+  );
+}
+
+export default CreditGrantDetailsPage;
+```