@blocklet/payment-react 1.20.16 → 1.20.17

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

@@ -0,0 +1,67 @@
+# 歷史記錄元件
+
+`@blocklet/payment-react` 函式庫提供了一套歷史記錄元件，旨在為您的使用者提供清晰詳細的過往活動檢視。這些元件對於建構客戶入口網站、帳戶儀表板和管理介面至關重要，在這些介面中，使用者需要追蹤他們的帳單、付款和點數使用情況。
+
+這些元件直接從支付服務中獲取並顯示資料，提供了一種無縫的方式來呈現歷史資訊，而無需從頭開始建構複雜的資料獲取和渲染邏輯。
+
+<x-cards data-columns="2">
+  <x-card data-title="CustomerInvoiceList" data-icon="lucide:receipt-text" data-href="/components/history/invoice-list">
+    渲染客戶的發票列表或表格，包含狀態、金額和建立日期等詳細資訊。
+  </x-card>
+  <x-card data-title="CustomerPaymentList" data-icon="lucide:credit-card" 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-card data-title="CreditTransactionsList" data-icon="lucide:history" data-href="/components/history/credit-transactions-list">
+    列出所有單獨的點數交易，提供隨時間變化的點數使用和調整的詳細日誌。
+  </x-card>
+</x-cards>
+
+## 常見使用案例
+
+一個典型的使用案例是在使用者的帳戶頁面中建立一個「帳務歷史」部分。您可以使用分頁介面在不同的歷史檢視之間切換，例如發票、付款和點數。
+
+以下是一個概念性範例，展示了您如何建構這樣一個頁面。
+
+```jsx MyBillingPage.tsx icon=lucide:user
+import React from 'react';
+import { CustomerInvoiceList, CustomerPaymentList } from '@blocklet/payment-react';
+
+// 假設您已從會話或上下文中獲取了客戶 ID
+const customerId = 'cus_xxxxxxxxxxxxxx';
+
+export default function MyBillingPage() {
+  // 在實際應用中，您會使用狀態來管理當前的分頁
+  const [activeTab, setActiveTab] = React.useState('invoices');
+
+  return (
+    <div>
+      <h1>Billing History</h1>
+      <nav>
+        <button onClick={() => setActiveTab('invoices')}>Invoices</button>
+        <button onClick={() => setActiveTab('payments')}>Payments</button>
+      </nav>
+
+      <div style={{ marginTop: '20px' }}>
+        {activeTab === 'invoices' && (
+          <CustomerInvoiceList 
+            customer_id={customerId} 
+            type="table" 
+          />
+        )}
+        {activeTab === 'payments' && (
+          <CustomerPaymentList 
+            customer_id={customerId} 
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+這個範例展示了如何輕鬆嵌入歷史記錄元件，為您的使用者提供全面的自助式帳務資訊。每個元件都會處理自己的資料獲取、分頁和顯示邏輯。
+
+探索每個元件的詳細文件，以了解其特定的 props 和自訂選項。

package/docs/components-history.zh.md

@@ -0,0 +1,67 @@
+# 历史组件
+
+`@blocklet/payment-react` 库提供了一套历史组件，旨在为您的用户提供清晰详细的过往活动视图。这些组件对于构建客户门户、账户仪表盘和管理界面至关重要，用户可以在这些界面中跟踪他们的账单、支付和信用使用情况。
+
+这些组件直接从支付服务中获取并显示数据，提供了一种无缝呈现历史信息的方式，无需从头开始构建复杂的数据获取和渲染逻辑。
+
+<x-cards data-columns="2">
+  <x-card data-title="CustomerInvoiceList" data-icon="lucide:receipt-text" data-href="/components/history/invoice-list">
+    渲染客户发票的列表或表格，包括状态、金额和创建日期的详细信息。
+  </x-card>
+  <x-card data-title="CustomerPaymentList" data-icon="lucide:credit-card" 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-card data-title="CreditTransactionsList" data-icon="lucide:history" data-href="/components/history/credit-transactions-list">
+    列出所有个人信用交易，提供信用使用和随时间调整的详细日志。
+  </x-card>
+</x-cards>
+
+## 常见用例
+
+一个典型的用例是在用户的账户页面中创建一个“账单历史”部分。您可以使用选项卡式界面在不同的历史视图之间切换，例如发票、支付和信用。
+
+下面是一个关于如何构建这样一个页面的概念性示例。
+
+```jsx MyBillingPage.tsx icon=lucide:user
+import React from 'react';
+import { CustomerInvoiceList, CustomerPaymentList } from '@blocklet/payment-react';
+
+// 假设您从会话或上下文中获取了客户的 ID
+const customerId = 'cus_xxxxxxxxxxxxxx';
+
+export default function MyBillingPage() {
+  // 在实际应用中，您会使用 state 来管理活动选项卡
+  const [activeTab, setActiveTab] = React.useState('invoices');
+
+  return (
+    <div>
+      <h1>Billing History</h1>
+      <nav>
+        <button onClick={() => setActiveTab('invoices')}>Invoices</button>
+        <button onClick={() => setActiveTab('payments')}>Payments</button>
+      </nav>
+
+      <div style={{ marginTop: '20px' }}>
+        {activeTab === 'invoices' && (
+          <CustomerInvoiceList 
+            customer_id={customerId} 
+            type="table" 
+          />
+        )}
+        {activeTab === 'payments' && (
+          <CustomerPaymentList 
+            customer_id={customerId} 
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+这个例子展示了如何轻松嵌入历史组件，为您的用户提供全面的自助式账单信息。每个组件都处理自己的数据获取、分页和显示逻辑。
+
+探索每个组件的详细文档，以了解其特定的属性和自定义选项。

package/docs/components-ui-form-elements-address-form.ja.md

@@ -0,0 +1,121 @@
+# AddressForm
+
+`AddressForm`コンポーネントは、請求先住所情報を収集するための構築済みUIを提供します。`react-hook-form`とシームレスに統合されており、郵便番号などのフィールドに対して国別の組み込みバリデーションが含まれています。
+
+このコンポーネントは柔軟に設計されており、完全な住所の収集と、Stripeの郵便番号検証用の簡易バージョンの両方をサポートしています。
+
+## Props
+
+| Prop              | Type                               | Description                                                                                                                              | Default         |
+| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `mode`            | `string`                           | 表示するフィールドを決定します。`'required'`に設定すると、完全な住所フォーム（住所1、市区町村、都道府県、郵便番号、国）が表示されます。       | `undefined`     |
+| `stripe`          | `boolean`                          | `true`の場合、郵便番号と国のみを含む簡易フォームを表示します。これは通常、Stripeでのカード検証に使用されます。             | `false`         |
+| `sx`              | `SxProps`                          | ルートの`Stack`コンポーネントをカスタムスタイリングするためのMUIの`sx`プロパティです。                                                                        | `{}`            |
+| `fieldValidation` | `Record<string, any>`              | 特定のフィールドに正規表現パターンなどのカスタムバリデーションルールを提供するためのオブジェクトです。詳細はバリデーションのセクションを参照してください。 | `{}`            |
+| `errorPosition`   | `'right'` \| `'bottom'`             | 入力フィールドに対してバリデーションエラーメッセージをどこに表示するかを指定します。                                                      | `'right'`       |
+
+## Usage
+
+`AddressForm`は、フィールドの登録と状態管理のために`react-hook-form`のコンテキストに依存しているため、`FormProvider`内で使用する必要があります。
+
+### 標準的な請求先住所
+
+完全な請求先住所を収集するには、`mode`プロパティを`'required'`に設定します。これにより、すべての標準的な住所フィールドが、それぞれ`'required'`のバリデーションルールと共にレンダリングされます。
+
+```tsx AddressForm with Full Address icon=material-symbols:location-on-outline
+import { FormProvider, useForm } from 'react-hook-form';
+import { Button, Stack } from '@mui/material';
+import AddressForm from './AddressForm'; // インポートパスを調整してください
+
+export default function FullAddressExample() {
+  const methods = useForm({
+    defaultValues: {
+      billing_address: {
+        line1: '',
+        city: '',
+        state: '',
+        postal_code: '',
+        country: 'US', // デフォルトの国
+      },
+    },
+  });
+
+  const onSubmit = (data) => {
+    console.log('Form data:', data);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Stack spacing={2}>
+          <AddressForm mode="required" />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+        </Stack>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+この設定では、住所、市区町村、都道府県、郵便番号の入力フィールドがレンダリングされます。国は、統合された[CountrySelect](./components-ui-form-elements-country-select.md)コンポーネントを介して選択されます。
+
+### Stripeの郵便番号検証
+
+Stripeのような決済方法を使用する場合、カード検証に必要なのは郵便番号と国のみであることがよくあります。`stripe`プロパティを`true`に設定すると、これら2つのフィールドのみを含む簡易フォームがレンダリングされます。
+
+```tsx AddressForm for Stripe icon=logos:stripe
+import { FormProvider, useForm } from 'react-hook-form';
+import { Button, Stack } from '@mui/material';
+import AddressForm from './AddressForm'; // インポートパスを調整してください
+
+export default function StripeAddressExample() {
+  const methods = useForm({
+    defaultValues: {
+      billing_address: {
+        postal_code: '',
+        country: 'US', // デフォルトの国
+      },
+    },
+  });
+
+  const onSubmit = (data) => {
+    console.log('Form data:', data);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Stack spacing={2}>
+          <AddressForm stripe={true} />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+        </Stack>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+## バリデーション
+
+このコンポーネントには、必須フィールドに対する自動バリデーションが含まれています。最も注目すべき機能は、動的な郵便番号バリデーションであり、選択された国に基づいてルールを調整します。
+
+- **必須フィールド**: 表示されるすべてのフィールドは自動的に必須としてマークされます。
+- **郵便番号**: バリデーションロジックは`validator/lib/isPostalCode`ライブラリを使用します。選択された国の標準形式（例：米国の場合は5桁、カナダの場合は英数字）に対して郵便番号の形式をチェックします。国の形式が明示的にサポートされていない場合は、一般的なバリデーションが適用されます。
+- **カスタムバリデーション**: `fieldValidation`プロパティを介して追加のバリデーションルールを渡すことができます。例えば、`state`フィールドに特定のパターンを適用するには：
+
+```tsx
+const customValidation = {
+  'billing_address.state': {
+    pattern: '^[A-Z]{2}$',
+    pattern_message: {
+      en: '州は2文字のコードでなければなりません。',
+    },
+  },
+};
+
+<AddressForm mode="required" fieldValidation={customValidation} />;
+```

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

@@ -0,0 +1,121 @@
+# AddressForm
+
+`AddressForm` 元件提供了一個預先建置的使用者介面，用於收集帳單地址資訊。它與 `react-hook-form` 無縫整合，並包含針對郵遞區號等欄位的內建、特定國家/地區的驗證。
+
+此元件設計靈活，支援完整地址收集和用於 Stripe 郵遞區號驗證的簡化版本。
+
+## Props
+
+| Prop              | Type                               | Description                                                                                                                              | Default         |
+| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `mode`            | `string`                           | 決定要顯示的欄位。設定為 `'required'` 以顯示完整的地址表單（地址第一行、城市、州/省、郵遞區號、國家/地區）。       | `undefined`     |
+| `stripe`          | `boolean`                          | 若為 `true`，則顯示一個僅包含郵遞區號和國家/地區的簡化表單，通常用於 Stripe 的卡片驗證。             | `false`         |
+| `sx`              | `SxProps`                          | MUI 的 `sx` prop，用於對根 `Stack` 元件進行自訂樣式設定。                                                                        | `{}`            |
+| `fieldValidation` | `Record<string, any>`              | 一個用於為特定欄位提供自訂驗證規則的物件，例如正規表示式模式。詳情請參閱驗證部分。 | `{}`            |
+| `errorPosition`   | `'right'` \| `'bottom'`             | 指定相對於輸入欄位的驗證錯誤訊息顯示位置。                                                      | `'right'`       |
+
+## Usage
+
+`AddressForm` 必須在 `react-hook-form` 的 `FormProvider` 內使用，因為它依賴其上下文來註冊欄位和管理狀態。
+
+### 標準帳單地址
+
+若要收集完整的帳單地址，請將 `mode` prop 設定為 `'required'`。這將呈現所有標準地址欄位，每個欄位都帶有「必填」驗證規則。
+
+```tsx 包含完整地址的 AddressForm icon=material-symbols:location-on-outline
+import { FormProvider, useForm } from 'react-hook-form';
+import { Button, Stack } from '@mui/material';
+import AddressForm from './AddressForm'; // 調整匯入路徑
+
+export default function FullAddressExample() {
+  const methods = useForm({
+    defaultValues: {
+      billing_address: {
+        line1: '',
+        city: '',
+        state: '',
+        postal_code: '',
+        country: 'US', // 預設國家/地區
+      },
+    },
+  });
+
+  const onSubmit = (data) => {
+    console.log('Form data:', data);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Stack spacing={2}>
+          <AddressForm mode="required" />
+          <Button type="submit" variant="contained">
+            提交
+          </Button>
+        </Stack>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+此設定會呈現地址、城市、州/省和郵遞區號的輸入欄位。國家/地區是透過整合的 [CountrySelect](./components-ui-form-elements-country-select.md) 元件來選擇。
+
+### Stripe 郵遞區號驗證
+
+當使用像 Stripe 這樣的支付方式時，通常只需要郵遞區號和國家/地區進行卡片驗證。將 `stripe` prop 設定為 `true`，以呈現僅包含這兩個欄位的簡化表單。
+
+```tsx 用於 Stripe 的 AddressForm icon=logos:stripe
+import { FormProvider, useForm } from 'react-hook-form';
+import { Button, Stack } from '@mui/material';
+import AddressForm from './AddressForm'; // 調整匯入路徑
+
+export default function StripeAddressExample() {
+  const methods = useForm({
+    defaultValues: {
+      billing_address: {
+        postal_code: '',
+        country: 'US', // 預設國家/地區
+      },
+    },
+  });
+
+  const onSubmit = (data) => {
+    console.log('Form data:', data);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Stack spacing={2}>
+          <AddressForm stripe={true} />
+          <Button type="submit" variant="contained">
+            提交
+          </Button>
+        </Stack>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+## 驗證
+
+該元件包含對必填欄位的自動驗證。最顯著的特點是動態郵遞區號驗證，它會根據所選國家/地區調整其規則。
+
+- **必填欄位**：所有可見欄位都會自動標記為必填。
+- **郵遞區號**：驗證邏輯使用 `validator/lib/isPostalCode` 函式庫。它會根據所選國家/地區的標準格式（例如，美國為 5 位數字，加拿大為字母數字）來檢查郵遞區號格式。如果某個國家/地區的格式未被明確支援，則會套用通用驗證。
+- **自訂驗證**：您可以透過 `fieldValidation` prop 傳遞額外的驗證規則。例如，若要對 `state` 欄位強制執行特定模式：
+
+```tsx
+const customValidation = {
+  'billing_address.state': {
+    pattern: '^[A-Z]{2}$',
+    pattern_message: {
+      en: '州/省必須是 2 個字母的代碼。',
+    },
+  },
+};
+
+<AddressForm mode="required" fieldValidation={customValidation} />;
+```

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

@@ -0,0 +1,121 @@
+# AddressForm
+
+`AddressForm` 组件提供了一个预构建的用户界面，用于收集账单地址信息。它与 `react-hook-form` 无缝集成，并包含针对邮政编码等字段的内置、特定国家/地区的验证。
+
+该组件设计灵活，既支持完整的地址收集，也支持用于 Stripe 邮政编码验证的简化版本。
+
+## Props
+
+| Prop              | Type                               | Description                                                                                                                              | Default         |
+| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `mode`            | `string`                           | 决定要显示的字段。设置为 `'required'` 以显示完整的地址表单（地址行 1、城市、州/省、邮政编码、国家/地区）。       | `undefined`     |
+| `stripe`          | `boolean`                          | 如果为 `true`，则显示一个仅包含邮政编码和国家/地区的简化表单，通常用于 Stripe 的银行卡验证。             | `false`         |
+| `sx`              | `SxProps`                          | MUI 的 `sx` 属性，用于对根 `Stack` 组件进行自定义样式设置。                                                                        | `{}`            |
+| `fieldValidation` | `Record<string, any>`              | 一个用于为特定字段提供自定义验证规则（例如正则表达式模式）的对象。有关详细信息，请参见验证部分。 | `{}`            |
+| `errorPosition`   | `'right'` \| `'bottom'`             | 指定在输入字段的哪个位置显示验证错误消息。                                                      | `'right'`       |
+
+## 用法
+
+`AddressForm` 必须在 `react-hook-form` 的 `FormProvider` 中使用，因为它依赖其上下文来注册字段和管理状态。
+
+### 标准账单地址
+
+要收集完整的账单地址，请将 `mode` 属性设置为 `'required'`。这将渲染所有标准的地址字段，每个字段都带有“必填”验证规则。
+
+```tsx AddressForm with Full Address icon=material-symbols:location-on-outline
+import { FormProvider, useForm } from 'react-hook-form';
+import { Button, Stack } from '@mui/material';
+import AddressForm from './AddressForm'; // 调整导入路径
+
+export default function FullAddressExample() {
+  const methods = useForm({
+    defaultValues: {
+      billing_address: {
+        line1: '',
+        city: '',
+        state: '',
+        postal_code: '',
+        country: 'US', // 默认国家/地区
+      },
+    },
+  });
+
+  const onSubmit = (data) => {
+    console.log('表单数据：', data);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Stack spacing={2}>
+          <AddressForm mode="required" />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+        </Stack>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+此设置会渲染地址行、城市、州/省和邮政编码的输入字段。国家/地区通过集成的 [CountrySelect](./components-ui-form-elements-country-select.md) 组件进行选择。
+
+### Stripe 邮政编码验证
+
+在使用 Stripe 等支付方式时，通常只需要邮政编码和国家/地区进行银行卡验证。将 `stripe` 属性设置为 `true` 以渲染一个仅包含这两个字段的简化表单。
+
+```tsx AddressForm for Stripe icon=logos:stripe
+import { FormProvider, useForm } from 'react-hook-form';
+import { Button, Stack } from '@mui/material';
+import AddressForm from './AddressForm'; // 调整导入路径
+
+export default function StripeAddressExample() {
+  const methods = useForm({
+    defaultValues: {
+      billing_address: {
+        postal_code: '',
+        country: 'US', // 默认国家/地区
+      },
+    },
+  });
+
+  const onSubmit = (data) => {
+    console.log('表单数据：', data);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Stack spacing={2}>
+          <AddressForm stripe={true} />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+        </Stack>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+## 验证
+
+该组件包含对必填字段的自动验证。最显著的特点是动态邮政编码验证，它会根据所选的国家/地区调整其规则。
+
+- **必填字段**：所有可见字段都会自动标记为必填。
+- **邮政编码**：验证逻辑使用 `validator/lib/isPostalCode` 库。它会根据所选国家/地区的标准格式（例如，美国的 5 位数字，加拿大的字母数字组合）检查邮政编码格式。如果某个国家/地区的格式未被明确支持，则会应用通用验证。
+- **自定义验证**：您可以通过 `fieldValidation` 属性传递额外的验证规则。例如，要对 `state` 字段强制执行特定模式：
+
+```tsx
+const customValidation = {
+  'billing_address.state': {
+    pattern: '^[A-Z]{2}$',
+    pattern_message: {
+      en: '州/省必须是 2 个字母的代码。',
+    },
+  },
+};
+
+<AddressForm mode="required" fieldValidation={customValidation} />;
+```

package/docs/components-ui-form-elements-country-select.ja.md

@@ -0,0 +1,126 @@
+# CountrySelect
+
+`CountrySelect`コンポーネントは、国を選択するための使いやすいドロップダウンを提供します。検索可能なリスト、国旗の表示、デスクトップとモバイルの両方のビューポートに適応するレスポンシブデザインが特徴です。`react-hook-form`で管理されるフォーム内での使用を想定して設計されています。
+
+## Props
+
+| Prop         | Type                             | 説明                                                                                | 必須 | デフォルト |
+|--------------|----------------------------------|---------------------------------------------------------------------------------------------|----------|---------|
+| `value`      | `CountryIso2`                    | 選択された国のISO2コード（例：「us」）。                                         | はい      |         |
+| `onChange`   | `(value: CountryIso2) => void`   | 国が選択されたときに呼び出されるコールバック関数。                             | はい      |         |
+| `name`       | `string`                         | 入力のname属性で、`react-hook-form`との統合に使用されます。              | はい      |         |
+| `sx`         | `SxProps`                        | ルート要素に適用されるカスタムスタイル。                                            | いいえ      | `{}`    |
+| `showDialCode` | `boolean`                        | `true`の場合、国のダイヤルコードがリストの名前の横に表示されます。        | いいえ      | `false` |
+
+## 基本的な使用法
+
+`CountrySelect`コンポーネントを使用するには、`react-hook-form`の`FormProvider`でラップする必要があります。コンポーネントの状態はフォームコンテキストを介して管理されます。
+
+```tsx Basic CountrySelect Example icon=logos:react
+import { FormProvider, useForm } from 'react-hook-form';
+import { Box, Button, Typography } from '@mui/material';
+import CountrySelect from '@blocklet/payment-react/src/components/country-select'; // 必要に応じてパスを調整
+import type { CountryIso2 } from 'react-international-phone';
+
+export default function BasicCountrySelect() {
+  const methods = useForm<{ country: CountryIso2 }>({
+    defaultValues: {
+      country: 'us',
+    },
+  });
+
+  const { handleSubmit, watch, setValue } = methods;
+  const countryValue = watch('country'); // 変更を監視して制御されたコンポーネントを更新
+
+  const onSubmit = (data: { country: CountryIso2 }) => {
+    alert(`国: ${data.country} でフォームが送信されました`);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={handleSubmit(onSubmit)}>
+        <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, maxWidth: 400 }}>
+          <Typography variant="h6">国を選択してください</Typography>
+          <CountrySelect
+            name="country"
+            value={countryValue}
+            onChange={(newCountry) => {
+              setValue('country', newCountry, { shouldValidate: true });
+            }}
+          />
+          <Button type="submit" variant="contained">
+            送信
+          </Button>
+          <Typography>
+            現在のフォーム値: {countryValue}
+          </Typography>
+        </Box>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+## 機能
+
+### 検索とフィルタリング
+コンポーネントにはドロップダウンリストの上部に検索バーがあり、ユーザーは国名、ISO2コード、またはダイヤルコードで国をすばやく見つけることができます。例えば、「+1」を検索すると、アメリカ合衆国とカナダが表示されます。
+
+### レスポンシブUI
+デスクトップデバイスでは、`CountrySelect`は標準のドロップダウンメニューとして表示されます。モバイルデバイスでは、画面下部からスライドアップする全幅のダイアログに変わり、小さなデバイスでも最適化されたユーザーエクスペリエンスを提供します。
+
+### キーボードアクセシビリティ
+`CountrySelect`は完全なキーボードナビゲーションをサポートしています。ユーザーは`ArrowUp`キーと`ArrowDown`キーでリストを移動し、`Enter`キーで国を選択し、`Escape`キーでドロップダウンを閉じることができます。`Tab`キーと`Shift+Tab`キーでもリスト項目を順に移動できます。
+
+### フォーム統合
+`react-hook-form`とシームレスに連携するように設計されています。選択が行われるとフォームの状態が自動的に更新されるため、`FormProvider`でラップする必要があります。
+
+## 高度な使用法
+
+### ダイヤルコードの表示
+
+`showDialCode`プロパティを`true`に設定すると、リスト内の各国の電話ダイヤルコードを表示できます。
+
+```tsx CountrySelect with Dial Code icon=logos:react
+import { FormProvider, useForm } from 'react-hook-form';
+import { Box, Button } from '@mui/material';
+import CountrySelect from '@blocklet/payment-react/src/components/country-select'; // 必要に応じてパスを調整
+import type { CountryIso2 } from 'react-international-phone';
+
+export default function CountrySelectWithDialCode() {
+  const methods = useForm<{ country: CountryIso2 }>({
+    defaultValues: {
+      country: 'gb',
+    },
+  });
+
+  const { handleSubmit, watch, setValue } = methods;
+  const countryValue = watch('country');
+
+  const onSubmit = (data: { country: CountryIso2 }) => {
+    alert(`国: ${data.country} でフォームが送信されました`);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={handleSubmit(onSubmit)}>
+        <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, maxWidth: 400 }}>
+          <CountrySelect
+            name="country"
+            value={countryValue}
+            onChange={(newCountry) => setValue('country', newCountry)}
+            showDialCode={true}
+          />
+          <Button type="submit" variant="contained">
+            送信
+          </Button>
+        </Box>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+## 次のステップ
+
+このコンポーネントは、より複雑なフォーム要素の構成要素です。完全な国際電話番号フィールドを作成するために、[PhoneInput](./components-ui-form-elements-phone-input.md)コンポーネントにどのように統合されているかを参照してください。