@blocklet/payment-react 1.20.16 → 1.20.17

package/docs/components-ui-pricing-table.zh-TW.md

@@ -0,0 +1,140 @@
+# PricingTable
+
+`PricingTable` 元件是一個彈性的 UI 元件，旨在以結構化、響應式的表格來顯示訂閱方案與價格選項。它允許使用者切換計費週期（例如，月繳、年繳）、選擇偏好的貨幣，並選擇一個方案以繼續進行。
+
+當您需要精細控制價格方案的呈現方式以建立自訂結帳流程時，此元件是理想的選擇。若需要一個能處理完整結帳流程的整合度更高的解決方案，請考慮使用更高階的 [`CheckoutTable`](./components-checkout-checkout-table.md) 元件。
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `table` | `TPricingTableExpanded` | - | **必填**。一個包含價格表資料的物件，包括項目（方案）列表、貨幣資訊和其他詳細資訊。 |
+| `onSelect` | `(priceId: string, currencyId: string) => void` | - | **必填**。當使用者點擊方案的動作按鈕時觸發的回呼函式。它會接收所選的 `priceId` 和 `currencyId`。 |
+| `alignItems` | `'center' \| 'left'` | `'center'` | 控制表格標頭內容（計費週期和貨幣選擇器）的水平對齊方式。 |
+| `mode` | `'checkout' \| 'select'` | `'checkout'` | 決定動作按鈕的行為和文字。`'checkout'` 模式用於啟動付款，而 `'select'` 模式用於在較大的表單中選擇方案。 |
+| `interval` | `string` | `''` | 設定初始選擇的計費間隔。格式通常為 `interval-interval_count`（例如 `month-1`、`year-1`）。 |
+| `hideCurrency` | `boolean` | `false` | 若為 `true`，即使有多種貨幣可用，貨幣選擇器下拉選單也將被隱藏。 |
+
+## 使用範例
+
+若要使用 `PricingTable`，您必須將其包裝在 `PaymentProvider` 中。該元件需要一個包含您產品資料的 `table` 物件，以及一個用於管理使用者選擇的 `onSelect` 處理函式。
+
+```tsx Integration Example icon=lucide:code
+import { PaymentProvider } from '@blocklet/payment-react';
+import { PricingTable } from '@blocklet/payment-react/components/ui';
+import type { TPricingTableExpanded } from '@blocklet/payment-types';
+
+// 在實際應用中，您會從您的支付服務中獲取此資料。
+const pricingTableData: TPricingTableExpanded = {
+  id: 'pt_123',
+  livemode: false,
+  currency: { id: 'usd', symbol: '$' },
+  items: [
+    {
+      price_id: 'price_basic_monthly',
+      product: {
+        name: 'Basic Plan',
+        description: 'For individuals and small teams.',
+        unit_label: 'user',
+        features: [{ name: '5 Projects' }, { name: '10GB Storage' }, { name: 'Basic Support' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '1000', // 以分為單位
+        recurring: { interval: 'month', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+      },
+      is_highlight: false,
+    },
+    {
+      price_id: 'price_pro_monthly',
+      product: {
+        name: 'Pro Plan',
+        description: 'For growing businesses.',
+        unit_label: 'user',
+        features: [{ name: 'Unlimited Projects' }, { name: '100GB Storage' }, { name: 'Priority Support' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '2500',
+        recurring: { interval: 'month', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '2500' }],
+      },
+      is_highlight: true,
+      highlight_text: 'Popular',
+    },
+    {
+      price_id: 'price_basic_yearly',
+      product: {
+        name: 'Basic Plan',
+        description: 'For individuals and small teams.',
+        unit_label: 'user',
+        features: [{ name: '5 Projects' }, { name: '10GB Storage' }, { name: 'Basic Support' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '10000',
+        recurring: { interval: 'year', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '10000' }],
+      },
+      is_highlight: false,
+    },
+    {
+      price_id: 'price_pro_yearly',
+      product: {
+        name: 'Pro Plan',
+        description: 'For growing businesses.',
+        unit_label: 'user',
+        features: [{ name: 'Unlimited Projects' }, { name: '100GB Storage' }, { name: 'Priority Support' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '25000',
+        recurring: { interval: 'year', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '25000' }],
+      },
+      is_highlight: true,
+      highlight_text: 'Popular',
+    },
+  ],
+};
+
+function MyPricingPage() {
+  const { session, connect } = useSessionContext();
+
+  const handlePlanSelect = async (priceId: string, currencyId: string) => {
+    console.log(`Plan selected: ${priceId}, Currency: ${currencyId}`);
+    // 在這裡，您通常會導向到結帳頁面或打開一個付款彈出視窗。
+    // 例如：`router.push("/checkout?price_id=${priceId}&currency_id=${currencyId}")`
+    alert(`Selected Price ID: ${priceId}`);
+  };
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <div style={{ maxWidth: 800, margin: 'auto' }}>
+        <PricingTable table={pricingTableData} onSelect={handlePlanSelect} />
+      </div>
+    </PaymentProvider>
+  );
+}
+
+export default MyPricingPage;
+```
+
+## 使用情境
+
+### 模式：`checkout` vs. `select`
+
+`mode` 屬性會改變行動呼籲按鈕以適應不同的使用案例。
+
+-   **`mode='checkout'` (預設):** 按鈕文字將根據情境顯示，例如「訂閱」或「開始試用」。此模式適用於使用者點擊後應立即啟動付款或結帳流程的情況。
+
+-   **`mode='select'`:** 按鈕文字將顯示「選擇」或「已選擇」。當價格表是較大表單或多步驟流程的一部分時，這非常有用。`onSelect` 回呼可用於更新應用程式狀態中所選擇的方案，且 UI 將視覺上指示目前選擇的方案。
+
+### 處理 `onSelect`
+
+`onSelect` 回呼是處理使用者互動的核心機制。它是一個非同步函式，會接收所選方案的 `priceId` 和 `currencyId`。您的應用程式邏輯應置於此處。常見的操作包括：
+
+-   將所選方案儲存在您的應用程式狀態中。
+-   將使用者重新導向至專用的結帳頁面，並將 `priceId` 作為 URL 參數傳遞。
+-   使用 `priceId` 與支付服務後端建立一個結帳會話，然後開啟一個付款表單。

package/docs/components-ui-pricing-table.zh.md

@@ -0,0 +1,140 @@
+# PricingTable
+
+`PricingTable` 组件是一个灵活的 UI 元素，旨在以结构化的响应式表格显示订阅计划和定价选项。它允许用户在计费周期（例如，月度、年度）之间切换，选择他们偏好的货币，并选择一个计划以继续。
+
+该组件非常适合用于构建需要对定价计划的呈现进行精细控制的自定义结账流程。如果需要一个能处理整个结账流程的更集成的解决方案，请考虑使用更高级别的 [`CheckoutTable`](./components-checkout-checkout-table.md) 组件。
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `table` | `TPricingTableExpanded` | - | **必需**。一个包含定价表数据的对象，包括项目（计划）列表、货币信息和其他详细信息。 |
+| `onSelect` | `(priceId: string, currencyId: string) => void` | - | **必需**。当用户点击计划的操作按钮时触发的回调函数。它接收所选的 `priceId` 和 `currencyId`。 |
+| `alignItems` | `'center' \| 'left'` | `'center'` | 控制表格头部内容（计费周期和货币选择器）的水平对齐方式。 |
+| `mode` | `'checkout' \| 'select'` | `'checkout'` | 决定操作按钮的行为和文本。`'checkout'` 模式用于发起支付，而 `'select'` 模式用于在更大的表单中选择一个计划。 |
+| `interval` | `string` | `''` | 设置初始选定的计费周期。格式通常是 `interval-interval_count`（例如，`month-1`，`year-1`）。 |
+| `hideCurrency` | `boolean` | `false` | 如果为 `true`，即使有多种货币可用，货币选择器下拉列表也将被隐藏。 |
+
+## 用法示例
+
+要使用 `PricingTable`，您必须将其包裹在 `PaymentProvider` 中。该组件需要一个包含您的产品数据的 `table` 对象和一个用于管理用户选择的 `onSelect` 处理程序。
+
+```tsx Integration Example icon=lucide:code
+import { PaymentProvider } from '@blocklet/payment-react';
+import { PricingTable } from '@blocklet/payment-react/components/ui';
+import type { TPricingTableExpanded } from '@blocklet/payment-types';
+
+// 在实际应用中，您将从支付服务中获取此数据。
+const pricingTableData: TPricingTableExpanded = {
+  id: 'pt_123',
+  livemode: false,
+  currency: { id: 'usd', symbol: '$' },
+  items: [
+    {
+      price_id: 'price_basic_monthly',
+      product: {
+        name: '基础计划',
+        description: '适用于个人和小型团队。',
+        unit_label: '用户',
+        features: [{ name: '5 个项目' }, { name: '10GB 存储空间' }, { name: '基础支持' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '1000', // 单位为美分
+        recurring: { interval: 'month', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+      },
+      is_highlight: false,
+    },
+    {
+      price_id: 'price_pro_monthly',
+      product: {
+        name: '专业版计划',
+        description: '适用于成长中的企业。',
+        unit_label: '用户',
+        features: [{ name: '无限项目' }, { name: '100GB 存储空间' }, { name: '优先支持' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '2500',
+        recurring: { interval: 'month', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '2500' }],
+      },
+      is_highlight: true,
+      highlight_text: '热门',
+    },
+    {
+      price_id: 'price_basic_yearly',
+      product: {
+        name: '基础计划',
+        description: '适用于个人和小型团队。',
+        unit_label: '用户',
+        features: [{ name: '5 个项目' }, { name: '10GB 存储空间' }, { name: '基础支持' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '10000',
+        recurring: { interval: 'year', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '10000' }],
+      },
+      is_highlight: false,
+    },
+    {
+      price_id: 'price_pro_yearly',
+      product: {
+        name: '专业版计划',
+        description: '适用于成长中的企业。',
+        unit_label: '用户',
+        features: [{ name: '无限项目' }, { name: '100GB 存储空间' }, { name: '优先支持' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '25000',
+        recurring: { interval: 'year', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '25000' }],
+      },
+      is_highlight: true,
+      highlight_text: '热门',
+    },
+  ],
+};
+
+function MyPricingPage() {
+  const { session, connect } = useSessionContext();
+
+  const handlePlanSelect = async (priceId: string, currencyId: string) => {
+    console.log(`已选择计划：${priceId}，货币：${currencyId}`);
+    // 在这里，您通常会导航到结账页面或打开一个支付模态框。
+    // 例如：`router.push(\"/checkout?price_id=${priceId}&currency_id=${currencyId}\")`
+    alert(`已选择价格 ID：${priceId}`);
+  };
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <div style={{ maxWidth: 800, margin: 'auto' }}>
+        <PricingTable table={pricingTableData} onSelect={handlePlanSelect} />
+      </div>
+    </PaymentProvider>
+  );
+}
+
+export default MyPricingPage;
+```
+
+## 使用场景
+
+### 模式：`checkout` vs. `select`
+
+`mode` prop 会更改号召性用语按钮以适应不同的用例。
+
+-   **`mode='checkout'` (默认):** 按钮文本将具有上下文感知能力，显示“订阅”或“开始试用”等标签。此模式旨在当用户的点击应立即启动支付或结账流程时使用。
+
+-   **`mode='select'`:** 按钮文本将显示“选择”或“已选择”。当定价表是更大表单或多步骤流程的一部分时，这非常有用。`onSelect` 回调可用于更新应用程序状态中的所选计划，并且 UI 将在视觉上指示当前选择的计划。
+
+### 处理 `onSelect`
+
+`onSelect` 回调是处理用户交互的核心机制。它是一个接收所选计划的 `priceId` 和 `currencyId` 的异步函数。您的应用程序逻辑应放在此处。常见操作包括：
+
+-   在应用程序的状态中存储所选的计划。
+-   将用户重定向到专用的结账页面，并将 `priceId` 作为 URL 参数传递。
+-   使用 `priceId` 与支付服务后端创建一个结账会话，然后打开一个支付表单。

package/docs/components-ui.ja.md

@@ -0,0 +1,71 @@
+# UIコンポーネント
+
+`@blocklet/payment-react` ライブラリは、支払いおよびチェックアウトインターフェースを構築する際に最大限の柔軟性を提供するために設計された、一連のきめ細かいUIコンポーネントを提供します。フロー全体をカプセル化する高レベルの[チェックアウトコンポーネント](./components-checkout.md)とは異なり、これらのコンポーネントはカスタムユーザーエクスペリエンスを作成するためのビルディングブロックです。
+
+これらのコンポーネントは、既存のアプリケーションレイアウトに支払い機能を統合する必要がある場合や、標準のチェックアウトフローが特定の設計要件を満たさない場合に最適です。
+
+<x-cards data-columns="3">
+  <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:form-input" data-href="/components/ui/form-elements">
+    住所、電話番号、国選択など、カスタムの支払いおよび連絡先情報フォームを構築するための特殊な入力コンポーネントのコレクションです。
+  </x-card>
+</x-cards>
+
+## 支払いUIの構成
+
+UIコンポーネントは、完全な支払いページを構築するために組み合わせて使用されることを意図しています。これらのコンポーネントのほとんどは、支払い方法や設定などのデータのために支払いコンテキストにアクセスする必要があるため、`PaymentProvider`内でレンダリングする必要があります。
+
+以下は、`PricingTable`と`PaymentSummary`を組み合わせてカスタムチェックアウトページを作成する方法の概念的な例です。
+
+```jsx カスタムチェックアウトページ icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { PricingTable, PaymentSummary } from '@blocklet/payment-react/components';
+// useSessionContext フックは PaymentProvider のドキュメントで定義されています
+import { useSessionContext } from '/path/to/session/context'; 
+
+function CustomCheckoutPage() {
+  const { session, connectApi } = useSessionContext();
+  
+  // 実際のアプリケーションでは、このデータをバックエンドから取得します
+  const pricingData = { /* ... 価格表データオブジェクト ... */ };
+  const selectedItems = [ /* ... ユーザーの選択に基づく明細項目 ... */ ];
+  const currency = { /* ... 通貨オブジェクト ... */ };
+
+  const handleSelect = (priceId, currencyId) => {
+    console.log('ユーザーが選択したプラン:', priceId, '通貨:', currencyId);
+    // 選択したプランを 'selectedItems' ステートに追加し、UIを更新します
+  };
+
+  return (
+    <PaymentProvider
+      apiHost={connectApi}
+      sessionId={session.user?.did}
+      locale="en"
+    >
+      <div className="checkout-container" style={{ display: 'flex', gap: '2rem' }}>
+        <div className="pricing-section" style={{ flex: 2 }}>
+          <h2>プランを選択してください</h2>
+          <PricingTable table={pricingData} onSelect={handleSelect} />
+        </div>
+        <div className="summary-section" style={{ flex: 1 }}>
+          <h2>注文概要</h2>
+          <PaymentSummary items={selectedItems} currency={currency} />
+        </div>
+      </div>
+    </PaymentProvider>
+  );
+}
+```
+
+この例では、`PricingTable`と`PaymentSummary`がカスタムページで一緒に使用されています。`PaymentProvider`が全体の構造をラップし、支払い設定とメソッドをすべての子コンポーネントで利用できるようにします。
+
+## 次のステップ
+
+UIコンポーネントの役割を理解したところで、各コンポーネントの詳細を掘り下げて、カスタム支払いフローの構築を始めましょう。`PricingTable`から始めることをお勧めします。
+
+[PricingTableコンポーネントについて学ぶ &rarr;](./components-ui-pricing-table.md)

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

@@ -0,0 +1,71 @@
+# UI 元件
+
+`@blocklet/payment-react` 函式庫提供了一組細粒度的 UI 元件，旨在為您在建構支付和結帳介面時提供最大的靈活性。與封裝整個流程的高階 [結帳元件](./components-checkout.md) 不同，這些元件是建立自訂使用者體驗的基礎。
+
+當您需要將支付功能整合到現有應用程式佈局中，或者當標準結帳流程不符合您的特定設計要求時，這些元件是理想的選擇。
+
+<x-cards data-columns="3">
+  <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:form-input" data-href="/components/ui/form-elements">
+    一系列專門的輸入元件，用於建構自訂的支付和聯絡資訊表單，例如地址、電話和國家選擇。
+  </x-card>
+</x-cards>
+
+## 組成您的支付 UI
+
+UI 元件旨在組合在一起以建構一個完整的支付頁面。這些元件大多需要存取支付上下文以獲取支付方式和設定等資料，因此它們必須在 `PaymentProvider` 內進行渲染。
+
+以下是一個概念性範例，說明如何結合 `PricingTable` 和 `PaymentSummary` 來建立一個自訂結帳頁面。
+
+```jsx A Custom Checkout Page icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { PricingTable, PaymentSummary } from '@blocklet/payment-react/components';
+// useSessionContext hook 在 PaymentProvider 文件中有定義
+import { useSessionContext } from '/path/to/session/context'; 
+
+function CustomCheckoutPage() {
+  const { session, connectApi } = useSessionContext();
+  
+  // 在實際應用中，您會從後端獲取此資料
+  const pricingData = { /* ... pricing table data object ... */ };
+  const selectedItems = [ /* ... line items based on user selection ... */ ];
+  const currency = { /* ... currency object ... */ };
+
+  const handleSelect = (priceId, currencyId) => {
+    console.log('使用者選擇的方案：', priceId, '使用的貨幣：', currencyId);
+    // 將所選方案新增到 'selectedItems' 狀態並更新 UI
+  };
+
+  return (
+    <PaymentProvider
+      apiHost={connectApi}
+      sessionId={session.user?.did}
+      locale="en"
+    >
+      <div className="checkout-container" style={{ display: 'flex', gap: '2rem' }}>
+        <div className="pricing-section" style={{ flex: 2 }}>
+          <h2>選擇您的方案</h2>
+          <PricingTable table={pricingData} onSelect={handleSelect} />
+        </div>
+        <div className="summary-section" style={{ flex: 1 }}>
+          <h2>訂單摘要</h2>
+          <PaymentSummary items={selectedItems} currency={currency} />
+        </div>
+      </div>
+    </PaymentProvider>
+  );
+}
+```
+
+在這個範例中，`PricingTable` 和 `PaymentSummary` 在一個自訂頁面上一起使用。`PaymentProvider` 包裹了整個結構，使得支付設定和方法對所有子元件都可用。
+
+## 下一步
+
+現在您已經了解了 UI 元件的作用，請深入了解每個元件的具體細節，開始建構您的自訂支付流程。我們建議從 `PricingTable` 開始。
+
+[了解 PricingTable 元件 &rarr;](./components-ui-pricing-table.md)

package/docs/components-ui.zh.md

@@ -0,0 +1,71 @@
+# UI 组件
+
+`@blocklet/payment-react` 库提供了一套粒度化的 UI 组件，旨在为您在构建支付和结账界面时提供最大的灵活性。与封装了整个流程的高级[结账组件](./components-checkout.md)不同，这些组件是用于创建自定义用户体验的构建块。
+
+当您需要将支付功能集成到现有应用程序布局中，或者当标准结账流程不满足您的特定设计要求时，这些组件是理想的选择。
+
+<x-cards data-columns="3">
+  <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:form-input" data-href="/components/ui/form-elements">
+    一组专门用于构建自定义支付和联系信息表单的输入组件，例如地址、电话和国家/地区选择。
+  </x-card>
+</x-cards>
+
+## 组合您的支付 UI
+
+UI 组件旨在组合在一起以构建一个完整的支付页面。这些组件中的大多数需要访问支付上下文以获取支付方式和设置等数据，因此它们必须在 `PaymentProvider` 中渲染。
+
+下面是一个概念性示例，说明如何结合 `PricingTable` 和 `PaymentSummary` 来创建一个自定义结账页面。
+
+```jsx 一个自定义结账页面 icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { PricingTable, PaymentSummary } from '@blocklet/payment-react/components';
+// useSessionContext 钩子在 PaymentProvider 文档中有定义
+import { useSessionContext } from '/path/to/session/context'; 
+
+function CustomCheckoutPage() {
+  const { session, connectApi } = useSessionContext();
+  
+  // 在实际应用中，您会从后端获取这些数据
+  const pricingData = { /* ... 定价表数据对象 ... */ };
+  const selectedItems = [ /* ... 基于用户选择的订单项 ... */ ];
+  const currency = { /* ... 货币对象 ... */ };
+
+  const handleSelect = (priceId, currencyId) => {
+    console.log('用户选择的计划:', priceId, '使用的货币:', currencyId);
+    // 将所选计划添加到 'selectedItems' 状态并更新 UI
+  };
+
+  return (
+    <PaymentProvider
+      apiHost={connectApi}
+      sessionId={session.user?.did}
+      locale="en"
+    >
+      <div className="checkout-container" style={{ display: 'flex', gap: '2rem' }}>
+        <div className="pricing-section" style={{ flex: 2 }}>
+          <h2>选择您的计划</h2>
+          <PricingTable table={pricingData} onSelect={handleSelect} />
+        </div>
+        <div className="summary-section" style={{ flex: 1 }}>
+          <h2>订单摘要</h2>
+          <PaymentSummary items={selectedItems} currency={currency} />
+        </div>
+      </div>
+    </PaymentProvider>
+  );
+}
+```
+
+在这个例子中，`PricingTable` 和 `PaymentSummary` 在一个自定义页面上一起使用。`PaymentProvider` 包装了整个结构，使支付设置和方法对所有子组件都可用。
+
+## 下一步
+
+现在您已经了解了 UI 组件的作用，接下来请深入了解每个组件的具体信息，开始构建您的自定义支付流程。我们建议从 `PricingTable` 开始。
+
+[了解 PricingTable 组件 &rarr;](./components-ui-pricing-table.md)

package/docs/components.ja.md

@@ -0,0 +1,122 @@
+# コンポーネント
+
+`@blocklet/payment-react` ライブラリは、支払い、サブスクリプション、寄付機能の開発を加速するために設計された、事前に構築されたReactコンポーネントの包括的なスイートを提供します。これらのコンポーネントは、完全なドロップインソリューションが必要な場合でも、カスタムエクスペリエンスを構築するためのきめ細かいUI要素が必要な場合でも、適切なツールを見つけやすいように分類されています。
+
+すべてのコンポーネントは、状態管理とAPI通信を処理する `PaymentProvider` コンテキスト内でシームレスに動作するように設計されています。
+
+## コンポーネントアーキテクチャ
+
+次の図は、高レベルのコンポーネントが通常どのように相互作用するかを示しています。`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>