@blocklet/payment-react 1.20.16 → 1.20.18

package/docs/components-ui-form-elements.zh.md

@@ -0,0 +1,91 @@
+# 表单元素
+
+`@blocklet/payment-react` 库提供了一系列精细的输入组件，旨在简化自定义支付和联系信息表单的创建。这些元素在构建时充分考虑了验证和用户体验，能够与 `react-hook-form` 顺畅集成，为数据收集提供了一个强大而灵活的解决方案。
+
+每个组件都被设计为一个独立的单元，让你可以将它们组合成满足你特定需求的复杂表单。以下是可用的表单元素概览。
+
+<x-cards data-columns="2">
+  <x-card data-title="AddressForm" data-icon="lucide:map-pin" data-href="/components/ui/form-elements/address-form">
+    一个预构建的表单，用于收集账单地址详情，并带有特定国家/地区的验证功能。
+  </x-card>
+  <x-card data-title="PhoneInput" data-icon="lucide:phone" data-href="/components/ui/form-elements/phone-input">
+    一个国际电话号码输入框，集成了国家/地区代码选择器和验证功能。
+  </x-card>
+  <x-card data-title="CountrySelect" data-icon="lucide:globe" data-href="/components/ui/form-elements/country-select">
+    一个可搜索的下拉菜单，用于选择国家/地区，配有国旗和移动端友好的用户界面。
+  </x-card>
+  <x-card data-title="CurrencySelector" data-icon="lucide:coins" data-href="/components/ui/form-elements/currency-selector">
+    一个允许用户从可用选项中选择其偏好支付货币的组件。
+  </x-card>
+</x-cards>
+
+## 通用使用模式
+
+这些表单元素旨在与 `react-hook-form` 的 `FormProvider` 一起使用。你可以组合它们来构建全面的表单，以捕获交易所需的所有必要信息。虽然每个组件都有其自己的一套属性，但它们共享一个通用的集成模式。
+
+下面是一个基本示例，展示了如何组合多个表单元素来创建一个用户信息表单：
+
+```jsx MyCustomForm.tsx icon=logos:react
+import { FormProvider, useForm } from 'react-hook-form';
+import { AddressForm, PhoneInput, CurrencySelector } from '@blocklet/payment-react';
+import { Button, Stack } from '@mui/material';
+
+// 假设 `availableCurrencies` 是从你的后端获取的
+const availableCurrencies = [
+  {
+    id: 'usd_xxx',
+    name: 'USD',
+    symbol: 'USD',
+    logo: 'url/to/usd_logo.png',
+    method: { id: 'stripe', name: 'Stripe' },
+  },
+  // ... 其他货币
+];
+
+function MyCustomForm() {
+  const methods = useForm({
+    defaultValues: {
+      currency: 'usd_xxx',
+      phone_number: '',
+      billing_address: {
+        line1: '',
+        city: '',
+        state: '',
+        postal_code: '',
+        country: 'US', // 使用 ISO2 代码
+      },
+    },
+  });
+
+  const onSubmit = (data) => {
+    console.log('表单数据已提交：', data);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Stack spacing={2}>
+          <CurrencySelector
+            value={methods.watch('currency')}
+            currencies={availableCurrencies}
+            onChange={(currencyId) => methods.setValue('currency', currencyId)}
+          />
+          <PhoneInput name="phone_number" label="Phone Number" required />
+          <AddressForm mode="required" stripe={false} />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+        </Stack>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+在此示例中，`CurrencySelector`、`PhoneInput` 和 `AddressForm` 组合在同一个表单中。`CurrencySelector` 用作与表单状态绑定的受控组件，而 `PhoneInput` 和 `AddressForm` 是非受控组件，它们会自动将其字段和验证规则注册到 `react-hook-form` 的上下文中。
+
+## 后续步骤
+
+要了解每个组件的具体属性和实现细节，请浏览它们各自的文档页面。
+
+从 [AddressForm](./components-ui-form-elements-address-form.md) 开始，了解如何收集账单信息。

package/docs/components-ui-payment-summary.ja.md

@@ -0,0 +1,109 @@
+# PaymentSummary
+
+`PaymentSummary`コンポーネントは、あらゆるチェックアウトプロセスにとって重要なUI要素です。すべての品目、トライアル期間情報、ステーキング要件、および最終的な合計金額を含む、注文の詳細な内訳を提供します。レスポンシブデザインになっており、モバイルデバイス向けにレイアウトを調整します。
+
+このコンポーネントは`ProductItem`および`ProductDonation`と連携してカート内の各アイテムをレンダリングし、クロスセルの適用や数量の変更などのユーザーインタラクションを処理します。
+
+## Props
+
+`PaymentSummary`コンポーネントは、その動作と表示をカスタマイズするために以下のプロパティを受け入れます:
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `items` | `TLineItemExpanded[]` | はい | サマリーに表示される品目の配列。 |
+| `currency` | `TPaymentCurrency` | はい | 金額をフォーマットするための通貨オブジェクト。 |
+| `trialInDays` | `number` | はい | 定期的なサブスクリプションのトライアル日数。 |
+| `billingThreshold` | `number` | はい | 請求しきい値金額。該当する場合、ステーキング計算で使用されます。 |
+| `trialEnd` | `number` | いいえ | トライアルが終了するUnixタイムスタンプ。`trialInDays`を上書きします。 |
+| `showStaking` | `boolean` | いいえ | `true`の場合、ステーキングの詳細を表示します。デフォルトは`false`です。 |
+| `onUpsell` | `(from: string, to: string) => void` | いいえ | ユーザーがアップセルオファーを受け入れたときのコールバック関数。 |
+| `onDownsell` | `(from: string) => void` | いいえ | ユーザーがアップセルオファーを元に戻したときのコールバック関数。 |
+| `onQuantityChange` | `(itemId: string, quantity: number) => void` | いいえ | アイテムの数量が変更されたときのコールバック関数。 |
+| `onChangeAmount` | `(itemId: string, amount: string) => void` | いいえ | 寄付のようなカスタム金額アイテムの金額を変更するためのコールバック。 |
+| `onApplyCrossSell` | `(crossSellId: string) => void` | いいえ | ユーザーがクロスセルアイテムを追加したときのコールバック関数。 |
+| `onCancelCrossSell` | `() => void` | いいえ | ユーザーがクロスセルアイテムを削除したときのコールバック関数。 |
+| `checkoutSessionId` | `string` | いいえ | チェックアウトセッションのID。潜在的なクロスセルアイテムを取得するために使用されます。 |
+| `crossSellBehavior` | `string` | いいえ | クロスセルアイテムの動作を定義します（例：`'required'`）。 |
+| `donationSettings` | `DonationSettings` | いいえ | 寄付アイテムの設定。 |
+| `action` | `string` | いいえ | "Order Summary"を置き換える、サマリーセクションのカスタムタイトル。 |
+| `completed` | `boolean` | いいえ | `true`の場合、数量調整などのインタラクティブな要素を無効にします。デフォルトは`false`です。 |
+
+## Usage
+
+`PaymentSummary`コンポーネントは`PaymentProvider`内に配置する必要があり、通常はより大きなチェックアウトフォームの一部として使用されます。品目と通貨情報を提供する必要があります。
+
+以下に`PaymentSummary`コンポーネントを統合する方法の基本的な例を示します。
+
+```tsx PaymentSummary Example icon=lucide:shopping-cart
+import React from 'react';
+import { PaymentProvider, PaymentSummary } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // セッションコンテキストのフック
+
+// デモ用のモックデータ
+const mockCurrency = {
+  id: 'usd_4573516104843264',
+  symbol: '$',
+  name: 'USD',
+  decimal: 2,
+  isDefault: true,
+};
+
+const mockItems = [
+  {
+    id: 'li_1',
+    price_id: 'price_1',
+    quantity: 1,
+    adjustable_quantity: { enabled: true, minimum: 1, maximum: 10 },
+    price: {
+      id: 'price_1',
+      type: 'recurring',
+      recurring: { interval: 'month', interval_count: 1, usage_type: 'licensed' },
+      unit_amount: '2000',
+      product: {
+        name: 'Pro Plan',
+        images: [],
+      },
+    },
+  },
+];
+
+export default function MyCheckoutPage() {
+  const { session, connectApi } = useSessionContext();
+
+  const handleQuantityChange = (itemId, newQuantity) => {
+    console.log(`Item ${itemId} quantity changed to ${newQuantity}`);
+    // ここで通常、状態を更新してチェックアウト情報を再取得します
+  };
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <PaymentSummary
+        items={mockItems}
+        currency={mockCurrency}
+        trialInDays={14}
+        billingThreshold={0}
+        showStaking={true}
+        onQuantityChange={handleQuantityChange}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+### ステーキングと合計の表示
+
+`showStaking`が`true`に設定されている場合、コンポーネントは定期的なアイテムに必要なステーキング金額を計算して表示します。即時支払いの金額とステーキングに必要な金額を分離し、ユーザーに明確な財務概要を提供します。最終的な合計はこれらの金額を組み合わせたものです。
+
+### トライアル期間の処理
+
+コンポーネントはトライアル期間をユーザーに明確に伝えます。`trialInDays`または`trialEnd`を渡すことで、「その後 $20.00 / 月」のようなメッセージが合計の下に表示され、トライアル終了後の定期的な請求についてユーザーに通知します。
+
+### インタラクティブ機能
+
+- **数量調整**: アイテムの`adjustable_quantity.enabled`が`true`に設定されている場合、`PaymentSummary`（その子コンポーネント`ProductItem`を介して）は数量を増減させるためのコントロールをレンダリングします。変更時に`onQuantityChange`コールバックがトリガーされます。
+- **アップセル/ダウンセル**: アップセル設定のある製品の場合、ユーザーがプランをアップグレードできるようにスイッチがレンダリングされます。`onUpsell`および`onDownsell`コールバックがこれらのアクションを処理します。
+- **クロスセル**: `checkoutSessionId`が提供されている場合、コンポーネントは推奨されるクロスセルアイテムを取得して表示できます。これらのアイテムを追加または削除するボタンは、`onApplyCrossSell`および`onCancelCrossSell`コールバックをトリガーします。
+
+### モバイルレスポンシブ
+
+モバイルデバイスでは、特に多くのアイテムがある注文の場合、スペースを節約するために製品リストはデフォルトで折りたたみ可能です。ユーザーはタップしてリストを展開または折りたたむことができ、小さな画面でよりクリーンでユーザーフレンドリーな体験を提供します。

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

@@ -0,0 +1,109 @@
+# PaymentSummary
+
+`PaymentSummary` 元件是任何結帳流程中至關重要的 UI 元素。它提供了訂單的詳細明細，包括所有訂單項目、試用期資訊、質押要求以及最終總金額。它的設計具有響應性，並能適應行動裝置的佈局。
+
+這個元件與 `ProductItem` 和 `ProductDonation` 協同工作，以呈現購物車中的每個項目，並處理使用者互動，例如應用交叉銷售或更改數量。
+
+## Props
+
+`PaymentSummary` 元件接受以下 props 以自訂其行為和顯示：
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `items` | `TLineItemExpanded[]` | 是 | 要在摘要中顯示的訂單項目陣列。 |
+| `currency` | `TPaymentCurrency` | 是 | 用於格式化金額的貨幣物件。 |
+| `trialInDays` | `number` | 是 | 循環訂閱的試用天數。 |
+| `billingThreshold` | `number` | 是 | 帳單門檻金額。如果適用，用於質押計算。 |
+| `trialEnd` | `number` | 否 | 試用結束時的 Unix 時間戳。會覆寫 `trialInDays`。 |
+| `showStaking` | `boolean` | 否 | 若為 `true`，則顯示質押詳細資訊。預設為 `false`。 |
+| `onUpsell` | `(from: string, to: string) => void` | 否 | 當使用者接受追加銷售優惠時的回呼函式。 |
+| `onDownsell` | `(from: string) => void` | 否 | 當使用者還原追加銷售優惠時的回呼函式。 |
+| `onQuantityChange` | `(itemId: string, quantity: number) => void` | 否 | 當項目數量變更時的回呼函式。 |
+| `onChangeAmount` | `(itemId: string, amount: string) => void` | 否 | 用於更改自訂金額項目（如捐贈）金額的回呼。 |
+| `onApplyCrossSell` | `(crossSellId: string) => void` | 否 | 當使用者新增交叉銷售項目時的回呼函式。 |
+| `onCancelCrossSell` | `() => void` | 否 | 當使用者移除交叉銷售項目時的回呼函式。 |
+| `checkoutSessionId` | `string` | 否 | 結帳會話的 ID，用於獲取潛在的交叉銷售項目。 |
+| `crossSellBehavior` | `string` | 否 | 定義交叉銷售項目的行為（例如：`'required'`）。 |
+| `donationSettings` | `DonationSettings` | 否 | 捐贈項目的設定。 |
+| `action` | `string` | 否 | 摘要區塊的自訂標題，取代「訂單摘要」。 |
+| `completed` | `boolean` | 否 | 若為 `true`，則停用數量調整等互動元素。預設為 `false`。 |
+
+## 用法
+
+`PaymentSummary` 元件應放置在 `PaymentProvider` 內，通常作為更大型結帳表單的一部分使用。您需要為其提供訂單項目和貨幣資訊。
+
+這是一個如何整合 `PaymentSummary` 元件的基本範例。
+
+```tsx PaymentSummary Example icon=lucide:shopping-cart
+import React from 'react';
+import { PaymentProvider, PaymentSummary } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // 您的 session context hook
+
+// 用於示範的模擬資料
+const mockCurrency = {
+  id: 'usd_4573516104843264',
+  symbol: '$',
+  name: 'USD',
+  decimal: 2,
+  isDefault: true,
+};
+
+const mockItems = [
+  {
+    id: 'li_1',
+    price_id: 'price_1',
+    quantity: 1,
+    adjustable_quantity: { enabled: true, minimum: 1, maximum: 10 },
+    price: {
+      id: 'price_1',
+      type: 'recurring',
+      recurring: { interval: 'month', interval_count: 1, usage_type: 'licensed' },
+      unit_amount: '2000',
+      product: {
+        name: 'Pro Plan',
+        images: [],
+      },
+    },
+  },
+];
+
+export default function MyCheckoutPage() {
+  const { session, connectApi } = useSessionContext();
+
+  const handleQuantityChange = (itemId, newQuantity) => {
+    console.log(`Item ${itemId} quantity changed to ${newQuantity}`);
+    // 在這裡您通常會更新您的狀態並重新獲取結帳資訊
+  };
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <PaymentSummary
+        items={mockItems}
+        currency={mockCurrency}
+        trialInDays={14}
+        billingThreshold={0}
+        showStaking={true}
+        onQuantityChange={handleQuantityChange}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+### 顯示質押與總計
+
+如果 `showStaking` 設定為 `true`，該元件將計算並顯示循環項目所需的質押金額。它會將立即支付的金額與質押所需的金額分開，為使用者提供清晰的財務摘要。最終總額是這些金額的總和。
+
+### 處理試用期
+
+該元件會向使用者清楚地傳達試用期資訊。透過傳遞 `trialInDays` 或 `trialEnd`，總額下方將顯示類似「之後每月 $20.00」的訊息，告知使用者試用結束後的循環收費。
+
+### 互動功能
+
+- **數量調整**：如果某個項目的 `adjustable_quantity.enabled` 設定為 `true`，`PaymentSummary`（透過其子元件 `ProductItem`）將呈現增加或減少數量的控制項。修改時會觸發 `onQuantityChange` 回呼。
+- **追加銷售/降級銷售**：對於具有追加銷售設定的產品，會呈現一個開關，讓使用者升級其方案。`onUpsell` 和 `onDownsell` 回呼會處理這些操作。
+- **交叉銷售**：如果提供了 `checkoutSessionId`，該元件可以獲取並顯示建議的交叉銷售項目。新增或移除這些項目的按鈕會觸發 `onApplyCrossSell` 和 `onCancelCrossSell` 回呼。
+
+### 行動裝置響應式設計
+
+在行動裝置上，產品列表預設是可折疊的，以節省空間，特別是對於包含許多項目的訂單。使用者可以點擊以展開或折疊列表，在較小的螢幕上提供更簡潔、更友善的使用者體驗。

package/docs/components-ui-payment-summary.zh.md

@@ -0,0 +1,109 @@
+# PaymentSummary
+
+`PaymentSummary` 组件是任何结账流程中至关重要的 UI 元素。它提供了订单的详细分类，包括所有订单项、试用期信息、质押要求和最终总金额。它的设计是响应式的，可以为移动设备调整其布局。
+
+该组件与 `ProductItem` 和 `ProductDonation` 协同工作，以渲染购物车中的每个商品，并处理用户交互，如应用交叉销售或更改数量。
+
+## Props
+
+`PaymentSummary` 组件接受以下 props 以自定义其行为和显示：
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `items` | `TLineItemExpanded[]` | 是 | 要在摘要中显示的订单项数组。 |
+| `currency` | `TPaymentCurrency` | 是 | 用于格式化金额的货币对象。 |
+| `trialInDays` | `number` | 是 | 周期性订阅的试用天数。 |
+| `billingThreshold` | `number` | 是 | 计费阈值金额。如果适用，用于质押计算。 |
+| `trialEnd` | `number` | 否 | 试用结束的 Unix 时间戳。会覆盖 `trialInDays`。 |
+| `showStaking` | `boolean` | 否 | 如果为 `true`，则显示质押详情。默认为 `false`。 |
+| `onUpsell` | `(from: string, to: string) => void` | 否 | 用户接受增销提议时的回调函数。 |
+| `onDownsell` | `(from: string) => void` | 否 | 用户恢复增销提议时的回调函数。 |
+| `onQuantityChange` | `(itemId: string, quantity: number) => void` | 否 | 更改商品数量时的回调函数。 |
+| `onChangeAmount` | `(itemId: string, amount: string) => void` | 否 | 用于更改自定义金额项目（如捐赠）金额的回调。 |
+| `onApplyCrossSell` | `(crossSellId: string) => void` | 否 | 用户添加交叉销售商品时的回调函数。 |
+| `onCancelCrossSell` | `() => void` | 否 | 用户移除交叉销售商品时的回调函数。 |
+| `checkoutSessionId` | `string` | 否 | 结账会话的 ID，用于获取潜在的交叉销售商品。 |
+| `crossSellBehavior` | `string` | 否 | 定义交叉销售商品的行为（例如，`'required'`）。 |
+| `donationSettings` | `DonationSettings` | 否 | 捐赠项目的配置。 |
+| `action` | `string` | 否 | 摘要部分的自定义标题，替换“订单摘要”。 |
+| `completed` | `boolean` | 否 | 如果为 `true`，则禁用数量调整等交互式元素。默认为 `false`。 |
+
+## 用法
+
+`PaymentSummary` 组件应放置在 `PaymentProvider` 中，并且通常用作更复杂的结账表单的一部分。你需要为其提供订单项和货币信息。
+
+以下是如何集成 `PaymentSummary` 组件的基本示例。
+
+```tsx PaymentSummary Example icon=lucide:shopping-cart
+import React from 'react';
+import { PaymentProvider, PaymentSummary } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // 你的会话上下文钩子
+
+// 用于演示的模拟数据
+const mockCurrency = {
+  id: 'usd_4573516104843264',
+  symbol: '$',
+  name: 'USD',
+  decimal: 2,
+  isDefault: true,
+};
+
+const mockItems = [
+  {
+    id: 'li_1',
+    price_id: 'price_1',
+    quantity: 1,
+    adjustable_quantity: { enabled: true, minimum: 1, maximum: 10 },
+    price: {
+      id: 'price_1',
+      type: 'recurring',
+      recurring: { interval: 'month', interval_count: 1, usage_type: 'licensed' },
+      unit_amount: '2000',
+      product: {
+        name: 'Pro Plan',
+        images: [],
+      },
+    },
+  },
+];
+
+export default function MyCheckoutPage() {
+  const { session, connectApi } = useSessionContext();
+
+  const handleQuantityChange = (itemId, newQuantity) => {
+    console.log(`Item ${itemId} quantity changed to ${newQuantity}`);
+    // 在这里，你通常会更新你的状态并重新获取结账信息
+  };
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <PaymentSummary
+        items={mockItems}
+        currency={mockCurrency}
+        trialInDays={14}
+        billingThreshold={0}
+        showStaking={true}
+        onQuantityChange={handleQuantityChange}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+### 显示质押和总计
+
+如果 `showStaking` 设置为 `true`，该组件将计算并显示周期性项目所需的质押金额。它将立即支付的金额与质押所需的金额分开，为用户提供清晰的财务摘要。最终总额是这些金额的总和。
+
+### 处理试用期
+
+该组件向用户清晰地传达试用期信息。通过传递 `trialInDays` 或 `trialEnd`，总额下方将显示类似“然后 $20.00 / 月”的消息，告知用户试用期结束后的周期性费用。
+
+### 交互功能
+
+- **数量调整**：如果一个项目的 `adjustable_quantity.enabled` 设置为 `true`，`PaymentSummary`（通过其子组件 `ProductItem`）将渲染用于增加或减少数量的控件。修改时会触发 `onQuantityChange` 回调。
+- **增销/减销**：对于具有增销配置的产品，会渲染一个开关，允许用户升级他们的计划。`onUpsell` 和 `onDownsell` 回调处理这些操作。
+- **交叉销售**：如果提供了 `checkoutSessionId`，该组件可以获取并显示建议的交叉销售商品。添加或移除这些商品的按钮会触发 `onApplyCrossSell` 和 `onCancelCrossSell` 回调。
+
+### 移动端响应式设计
+
+在移动设备上，产品列表默认是可折叠的以节省空间，特别是对于包含许多商品的订单。用户可以点击以展开或折叠列表，从而在较小的屏幕上提供更清晰、更友好的用户体验。

package/docs/components-ui-pricing-table.ja.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'` (デフォルト):** ボタンのテキストはコンテキストに応じて、「Subscribe」や「Start Trial」などのラベルを表示します。このモードは、ユーザーのクリックが直ちに支払いまたはチェックアウトプロセスを開始する場合に使用します。
+
+-   **`mode='select'`:** ボタンのテキストは「Select」または「Selected」と表示されます。これは、価格表がより大きなフォームや複数ステップのプロセスの一部である場合に便利です。`onSelect` コールバックを使用して、選択されたプランでアプリケーションの状態を更新でき、UI は現在どのプランが選択されているかを視覚的に示します。
+
+### `onSelect` の処理
+
+`onSelect` コールバックは、ユーザーインタラクションを処理するための中心的なメカニズムです。これは選択されたプランの `priceId` と `currencyId` を受け取る非同期関数です。アプリケーションのロジックはここに記述します。一般的なアクションは次のとおりです：
+
+-   選択したプランをアプリケーションの状態に保存する。
+-   ユーザーを専用のチェックアウトページにリダイレクトし、`priceId` を URL パラメータとして渡す。
+-   `priceId` を使用して支払いサービスのバックエンドでチェックアウトセッションを作成し、支払いフォームを開く。