@blocklet/payment-react 1.20.16 → 1.20.18

package/docs/components.zh-TW.md

@@ -0,0 +1,122 @@
+# 元件
+
+`@blocklet/payment-react` 函式庫提供了一套全面的預建 React 元件，旨在加速支付、訂閱和捐贈功能的開發。這些元件經過分類，以幫助您為工作找到合適的工具，無論您需要一個完整的即插即用解決方案，還是需要精細的 UI 元素來建立自訂體驗。
+
+所有元件都設計為在 `PaymentProvider` 上下文中無縫工作，該上下文處理狀態管理和 API 通訊。
+
+## 元件架構
+
+下圖說明了高階元件通常如何互動。面向使用者的元件，如 `CheckoutTable` 或 `CheckoutDonate`，作為入口點，然後利用核心的 `CheckoutForm` 來處理最終的支付處理。
+
+```d2
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+PaymentProvider-Context: {
+  label: "PaymentProvider 上下文"
+  shape: rectangle
+  style: {
+    stroke: "#888"
+    stroke-width: 2
+    stroke-dash: 4
+  }
+
+  Entry-Points: {
+    label: "高階元件"
+    shape: rectangle
+
+    CheckoutTable: {
+      label: "CheckoutTable"
+    }
+
+    CheckoutDonate: {
+      label: "CheckoutDonate"
+    }
+  }
+
+  Core-Processor: {
+    label: "核心支付處理器"
+    shape: rectangle
+
+    CheckoutForm: {
+      label: "CheckoutForm"
+    }
+  }
+}
+
+User -> PaymentProvider-Context.Entry-Points.CheckoutTable: "選擇一個方案"
+User -> PaymentProvider-Context.Entry-Points.CheckoutDonate: "進行一次捐贈"
+PaymentProvider-Context.Entry-Points.CheckoutTable -> PaymentProvider-Context.Core-Processor.CheckoutForm: "啟動結帳"
+PaymentProvider-Context.Entry-Points.CheckoutDonate -> PaymentProvider-Context.Core-Processor.CheckoutForm: "啟動結帳"
+```
+
+## 元件類別
+
+探索我們的元件類別，找到您需要的建構區塊。
+
+### 結帳元件
+
+這些是高階元件，提供完整、開箱即用的支付體驗。將它們用作您支付流程的主要入口點。
+
+<x-cards>
+  <x-card data-title="CheckoutForm" data-icon="lucide:credit-card" data-href="/components/checkout/checkout-form">
+    處理支付連結和結帳工作階段的主要元件。
+  </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>
+
+### UI 元件
+
+用於建立自訂支付表單和顯示的精細元件集合。結合這些區塊，建立一個與您應用程式設計完美匹配的使用者介面。
+
+<x-cards>
+  <x-card data-title="PricingTable" data-icon="lucide:layout-list" data-href="/components/ui/pricing-table">
+    在結構化表格中顯示訂閱方案和價格選項。
+  </x-card>
+  <x-card data-title="PaymentSummary" data-icon="lucide:receipt" data-href="/components/ui/payment-summary">
+    顯示訂單的詳細摘要，包括項目和總計。
+  </x-card>
+  <x-card data-title="Form Elements" data-icon="lucide:pencil-ruler" data-href="/components/ui/form-elements">
+    用於建立自訂支付和聯絡表單的輸入元件集合。
+  </x-card>
+</x-cards>
+
+### 業務邏輯元件
+
+旨在處理複雜業務工作流程的專用元件，例如管理逾期發票、恢復訂閱和設定自動點數儲值。
+
+<x-cards>
+  <x-card data-title="OverdueInvoicePayment" data-icon="lucide:file-warning" data-href="/components/business/overdue-invoice-payment">
+    處理客戶或訂閱的逾期發票付款。
+  </x-card>
+  <x-card data-title="ResumeSubscription" data-icon="lucide:play-circle" data-href="/components/business/resume-subscription">
+    讓使用者輕鬆地恢復已取消的訂閱。
+  </x-card>
+  <x-card data-title="Auto-Topup Components" data-icon="lucide:battery-charging" data-href="/components/business/auto-topup">
+    管理和設定自動點數儲值功能。
+  </x-card>
+</x-cards>
+
+### 歷史記錄元件
+
+向您的使用者顯示歷史支付和點數資料。這些元件可以輕鬆呈現發票、付款和點數交易的列表。
+
+<x-cards>
+  <x-card data-title="CustomerInvoiceList" data-icon="lucide:history" data-href="/components/history/invoice-list">
+    呈現客戶的發票列表，包含詳細資訊和狀態。
+  </x-card>
+  <x-card data-title="CustomerPaymentList" data-icon="lucide:landmark" data-href="/components/history/payment-list">
+    顯示客戶的付款歷史，包括交易詳情。
+  </x-card>
+  <x-card data-title="CreditGrantsList" data-icon="lucide:award" data-href="/components/history/credit-grants-list">
+    顯示點數授予列表，包括狀態和剩餘金額。
+  </x-card>
+</x-cards>

package/docs/components.zh.md

@@ -0,0 +1,122 @@
+# 组件
+
+`@blocklet/payment-react` 库提供了一套全面的预构建 React 组件，旨在加速支付、订阅和捐赠功能的开发。这些组件进行了分类，以帮助您找到适合工作的工具，无论您需要的是完整的即用型解决方案，还是用于构建自定义体验的精细 UI 元素。
+
+所有组件都设计为在 `PaymentProvider` 上下文中无缝工作，该上下文负责处理状态管理和 API 通信。
+
+## 组件架构
+
+下图说明了高级组件通常如何交互。面向用户的组件（如 `CheckoutTable` 或 `CheckoutDonate`）作为入口点，然后利用核心的 `CheckoutForm` 来处理最终的支付流程。
+
+```d2
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+PaymentProvider-Context: {
+  label: "PaymentProvider 上下文"
+  shape: rectangle
+  style: {
+    stroke: "#888"
+    stroke-width: 2
+    stroke-dash: 4
+  }
+
+  Entry-Points: {
+    label: "高级组件"
+    shape: rectangle
+
+    CheckoutTable: {
+      label: "CheckoutTable"
+    }
+
+    CheckoutDonate: {
+      label: "CheckoutDonate"
+    }
+  }
+
+  Core-Processor: {
+    label: "核心支付处理器"
+    shape: rectangle
+
+    CheckoutForm: {
+      label: "CheckoutForm"
+    }
+  }
+}
+
+User -> PaymentProvider-Context.Entry-Points.CheckoutTable: "选择一个计划"
+User -> PaymentProvider-Context.Entry-Points.CheckoutDonate: "进行捐赠"
+PaymentProvider-Context.Entry-Points.CheckoutTable -> PaymentProvider-Context.Core-Processor.CheckoutForm: "发起结账"
+PaymentProvider-Context.Entry-Points.CheckoutDonate -> PaymentProvider-Context.Core-Processor.CheckoutForm: "发起结账"
+```
+
+## 组件分类
+
+浏览我们的组件分类，找到您需要的构建模块。
+
+### 结账组件
+
+这些是高级组件，提供完整的、开箱即用的支付体验。将它们用作您支付流程的主要入口点。
+
+<x-cards>
+  <x-card data-title="CheckoutForm" data-icon="lucide:credit-card" data-href="/components/checkout/checkout-form">
+    用于处理支付链接和结账会话的主要组件。
+  </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>
+
+### UI 组件
+
+一组用于构建自定义支付表单和显示的精细组件。组合这些模块，创建一个与您的应用程序设计完美匹配的用户界面。
+
+<x-cards>
+  <x-card data-title="PricingTable" data-icon="lucide:layout-list" data-href="/components/ui/pricing-table">
+    以结构化表格的形式显示订阅计划和价格选项。
+  </x-card>
+  <x-card data-title="PaymentSummary" data-icon="lucide:receipt" data-href="/components/ui/payment-summary">
+    显示订单的详细摘要，包括订单项和总计。
+  </x-card>
+  <x-card data-title="Form Elements" data-icon="lucide:pencil-ruler" data-href="/components/ui/form-elements">
+    用于构建自定义支付和联系表单的输入集合。
+  </x-card>
+</x-cards>
+
+### 业务逻辑组件
+
+专门用于处理复杂业务工作流的组件，例如管理逾期发票、恢复订阅和配置自动信用充值。
+
+<x-cards>
+  <x-card data-title="OverdueInvoicePayment" data-icon="lucide:file-warning" data-href="/components/business/overdue-invoice-payment">
+    处理客户或订阅的逾期发票支付。
+  </x-card>
+  <x-card data-title="ResumeSubscription" data-icon="lucide:play-circle" data-href="/components/business/resume-subscription">
+    允许用户轻松恢复已取消的订阅。
+  </x-card>
+  <x-card data-title="Auto-Topup Components" data-icon="lucide:battery-charging" data-href="/components/business/auto-topup">
+    管理和配置自动信用充值功能。
+  </x-card>
+</x-cards>
+
+### 历史组件
+
+向您的用户显示历史支付和信用数据。这些组件可以轻松渲染发票、支付和信用交易列表。
+
+<x-cards>
+  <x-card data-title="CustomerInvoiceList" data-icon="lucide:history" data-href="/components/history/invoice-list">
+    渲染客户的发票列表，包含详细信息和状态。
+  </x-card>
+  <x-card data-title="CustomerPaymentList" data-icon="lucide:landmark" data-href="/components/history/payment-list">
+    显示客户的支付历史，包括交易详情。
+  </x-card>
+  <x-card data-title="CreditGrantsList" data-icon="lucide:award" data-href="/components/history/credit-grants-list">
+    显示信用授予列表，包括状态和剩余金额。
+  </x-card>
+</x-cards>

package/docs/getting-started.ja.md

@@ -0,0 +1,84 @@
+# はじめに
+
+このガイドでは、`@blocklet/payment-react`をインストールし、基本的で機能的な支払いフォームをアプリケーションに統合するための重要な手順を説明します。わずか数分で、動作するチェックアウト体験を構築できます。
+
+## ステップ1：インストール
+
+まず、npmまたはお好みのパッケージマネージャーを使用して、ライブラリをプロジェクトに追加します。
+
+```bash Installation Command icon=lucide:terminal
+npm install @blocklet/payment-react
+```
+
+## ステップ2：PaymentProviderのセットアップ
+
+このライブラリのほとんどのコンポーネントは、共有の支払いコンテキストへのアクセスを必要とします。`PaymentProvider`コンポーネントがこのコンテキストを提供し、支払いが処理されるアプリケーションまたはコンポーネントツリーのルートに配置する必要があります。
+
+正しく動作するためには、アプリケーションの認証コンテキストから`session`オブジェクトと`connect` API関数が必要です。
+
+```tsx App.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+// これはアプリの認証コンテキストフックのプレースホルダーです。
+// 現在のユーザーセッションとAPIコネクタを返す必要があります。
+import { useSessionContext } from './contexts/session'; 
+
+function App({ children }) {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      {/* 支払コンポーネントはここに配置されます */}
+      {children}
+    </PaymentProvider>
+  );
+}
+```
+
+> セッションコンテキストの設定や高度な`PaymentProvider`の設定に関する詳細については、[PaymentProviderのドキュメント](./providers-payment-provider.md)をご覧ください。
+
+## ステップ3：CheckoutFormの追加
+
+`CheckoutForm`は、支払いフローをレンダリングするための主要なコンポーネントです。支払いリンクから開始される一回限りの支払いとサブスクリプションの両方を処理できます。
+
+使用するには、単に`PaymentProvider`内に配置し、支払いリンク（`plink_...`）またはチェックアウトセッション（`cs_...`）の必須`id`を渡します。
+
+## 完全な例
+
+上記の手順を組み合わせた、完全で最小限の例を以下に示します。このコードを統合の開始点として使用できます。
+
+```tsx PaymentPage.tsx icon=logos:react
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+// これはアプリの認証コンテキストフックのプレースホルダーです。
+import { useSessionContext } from './contexts/session'; 
+
+function PaymentPage() {
+  const { session, connectApi } = useSessionContext();
+
+  // 支払いリンクIDは、Payment Kitダッシュボードから生成されます。
+  const paymentLinkId = 'plink_xxx'; 
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm 
+        id={paymentLinkId}
+        mode="inline" // フォームをページに直接埋め込みます
+        showCheckoutSummary={true}
+        onChange={(state) => console.log('Checkout State Changed:', state)}
+        onPaid={(result) => console.log('Payment Successful:', result)}
+      />
+    </PaymentProvider>
+  );
+}
+
+export default PaymentPage;
+```
+
+この設定により、`CheckoutForm`は完全な支払いUIをレンダリングし、ユーザー入力を処理し、トランザクションをシームレスに処理します。
+
+## 次のステップ
+
+おめでとうございます！最初の支払いフォームの統合に成功しました。これで、より高度な機能やコンポーネントを探求する準備が整いました。
+
+- **[CheckoutForm](./components-checkout-checkout-form.md)**: `CheckoutForm`のプロパティとカスタマイズオプションについてさらに詳しく学びます。
+- **[Providers](./providers.md)**: ライブラリを支えるコンテキストプロバイダーについて詳しく学びます。
+- **[Components](./components.md)**: 利用可能なUIおよびビジネスロジックコンポーネントの全範囲を発見します。

package/docs/getting-started.zh-TW.md

@@ -0,0 +1,84 @@
+# 入門指南
+
+本指南將引導您完成安裝 `@blocklet/payment-react` 並將一個基本的、功能齊全的支付表單整合到您的應用程式中的必要步驟。只需幾分鐘，您就能擁有一個可運作的結帳體驗。
+
+## 步驟 1：安裝
+
+首先，使用 npm 或您偏好的套件管理器將該函式庫新增至您的專案中。
+
+```bash Installation Command icon=lucide:terminal
+npm install @blocklet/payment-react
+```
+
+## 步驟 2：設定 PaymentProvider
+
+此函式庫中的大多數元件都需要存取共用的支付上下文。`PaymentProvider` 元件提供了這個上下文，並且必須放置在您的應用程式或將處理支付的元件樹的根部。
+
+它需要來自您應用程式身份驗證上下文的 `session` 物件和 `connect` API 函式才能正常運作。
+
+```tsx App.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+// 這是您應用程式身份驗證上下文掛鉤的佔位符。
+// 它應返回當前使用者會話和一個 API 連接器。
+import { useSessionContext } from './contexts/session'; 
+
+function App({ children }) {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      {/* 您的支付元件將會放在這裡 */}
+      {children}
+    </PaymentProvider>
+  );
+}
+```
+
+> 有關設定您的會話上下文和進階 `PaymentProvider` 配置的詳細資訊，請參閱 [PaymentProvider 文件](./providers-payment-provider.md)。
+
+## 步驟 3：新增 CheckoutForm
+
+`CheckoutForm` 是呈現支付流程的主要元件。它可以處理從支付連結發起的單次支付和訂閱。
+
+要使用它，只需將其放置在 `PaymentProvider` 內部，並傳入支付連結（`plink_...`）或結帳會話（`cs_...`）所需的 `id`。
+
+## 完整範例
+
+這是一個結合了上述步驟的完整、最小化的範例。您可以使用此程式碼作為整合的起點。
+
+```tsx PaymentPage.tsx icon=logos:react
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+// 這是您應用程式身份驗證上下文掛鉤的佔位符。
+import { useSessionContext } from './contexts/session'; 
+
+function PaymentPage() {
+  const { session, connectApi } = useSessionContext();
+
+  // 支付連結 ID 是從您的 Payment Kit 儀表板生成的。
+  const paymentLinkId = 'plink_xxx'; 
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm 
+        id={paymentLinkId}
+        mode="inline" // 將表單直接嵌入到您的頁面中
+        showCheckoutSummary={true}
+        onChange={(state) => console.log('Checkout State Changed:', state)}
+        onPaid={(result) => console.log('Payment Successful:', result)}
+      />
+    </PaymentProvider>
+  );
+}
+
+export default PaymentPage;
+```
+
+透過此設定，`CheckoutForm` 將呈現一個完整的支付使用者介面，處理使用者輸入，並無縫地處理交易。
+
+## 後續步驟
+
+恭喜！您已成功整合您的第一個支付表單。現在您可以開始探索更多進階功能和元件。
+
+- **[CheckoutForm](./components-checkout-checkout-form.md)**：深入了解 `CheckoutForm` 的屬性和自訂選項。
+- **[Providers](./providers.md)**：了解更多關於支援此函式庫的上下文提供者。
+- **[Components](./components.md)**：探索所有可用的 UI 和業務邏輯元件。

package/docs/getting-started.zh.md

@@ -0,0 +1,84 @@
+# 快速入门
+
+本指南将引导您完成安装 `@blocklet/payment-react` 并将一个基础、功能齐全的支付表单集成到您的应用程序中的基本步骤。只需几分钟，您就可以拥有一个可用的结账体验。
+
+## 第 1 步：安装
+
+首先，使用 npm 或您偏好的包管理器将该库添加到您的项目中。
+
+```bash Installation Command icon=lucide:terminal
+npm install @blocklet/payment-react
+```
+
+## 第 2 步：设置 PaymentProvider
+
+此库中的大多数组件都需要访问共享的支付上下文。`PaymentProvider` 组件提供了此上下文，并且必须放置在将处理支付的应用程序或组件树的根部。
+
+它需要来自您应用程序身份验证上下文的 `session` 对象和 `connect` API 函数才能正常工作。
+
+```tsx App.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+// 这是您应用程序身份验证上下文钩子的占位符。
+// 它应返回当前用户会话和一个 API 连接器。
+import { useSessionContext } from './contexts/session'; 
+
+function App({ children }) {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      {/* 您的支付组件将放在这里 */}
+      {children}
+    </PaymentProvider>
+  );
+}
+```
+
+> 有关设置会话上下文和高级 `PaymentProvider` 配置的详细信息，请参阅 [PaymentProvider 文档](./providers-payment-provider.md)。
+
+## 第 3 步：添加 CheckoutForm
+
+`CheckoutForm` 是用于呈现支付流程的主要组件。它可以处理一次性支付和通过支付链接发起的订阅。
+
+要使用它，只需将其放置在 `PaymentProvider` 内部，并传递支付链接 (`plink_...`) 或结账会话 (`cs_...`) 所需的 `id`。
+
+## 完整示例
+
+这是一个结合了以上步骤的完整、最小化的示例。您可以使用此代码作为集成的起点。
+
+```tsx PaymentPage.tsx icon=logos:react
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+// 这是您应用程序身份验证上下文钩子的占位符。
+import { useSessionContext } from './contexts/session'; 
+
+function PaymentPage() {
+  const { session, connectApi } = useSessionContext();
+
+  // 支付链接 ID 是从您的 Payment Kit 仪表板生成的。
+  const paymentLinkId = 'plink_xxx'; 
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm 
+        id={paymentLinkId}
+        mode="inline" // 将表单直接嵌入到您的页面中
+        showCheckoutSummary={true}
+        onChange={(state) => console.log('Checkout State Changed:', state)}
+        onPaid={(result) => console.log('Payment Successful:', result)}
+      />
+    </PaymentProvider>
+  );
+}
+
+export default PaymentPage;
+```
+
+通过此设置，`CheckoutForm` 将呈现一个完整的支付 UI，处理用户输入，并无缝处理交易。
+
+## 后续步骤
+
+恭喜！您已成功集成您的第一个支付表单。现在，您可以开始探索更高级的功能和组件了。
+
+- **[CheckoutForm](./components-checkout-checkout-form.md)**：深入了解 `CheckoutForm` 的 props 和自定义选项。
+- **[Providers](./providers.md)**：了解更多关于支持该库的上下文提供程序的信息。
+- **[Components](./components.md)**：发现可用的全系列 UI 和业务逻辑组件。