@blocklet/payment-react 1.20.15 → 1.20.17

package/docs/components-ui-form-elements-phone-input.ja.md

@@ -0,0 +1,138 @@
+# PhoneInput
+
+`PhoneInput`コンポーネントは、ユーザーフレンドリーな国際電話番号入力フィールドを提供します。`react-hook-form`とシームレスに統合され、国旗と国番号付きの検索可能な国選択機能、自動番号フォーマット、および`google-libphonenumber`による強力な検証機能を備えています。
+
+このコンポーネントは、選択された国を共有フォームフィールドと同期させることで、[`CountrySelect`](./components-ui-form-elements-country-select.md)や[`AddressForm`](./components-ui-form-elements-address-form.md)などの他のフォーム要素と連携して動作するように設計されています。
+
+## 仕組み
+
+このコンポーネントは、`react-international-phone`ライブラリをコア機能として活用し、それをラップして`react-hook-form`およびMaterial-UIとの深い統合を提供します。ユーザーが国を選択したり番号を入力したりすると、コンポーネントはフォームの状態にある対応するフィールドを更新します。また、他のコンポーネントがフォーム内のリンクされた国フィールドを変更すると、自動的に国選択を更新します。
+
+```d2
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Form-State: {
+  label: "React Hook Form の状態"
+  shape: cylinder
+}
+
+PhoneInput-Component: {
+  label: "PhoneInput コンポーネント"
+
+  CountrySelect: {
+    label: "CountrySelect"
+  }
+
+  Phone-Field: {
+    label: "電話番号テキストフィールド"
+  }
+}
+
+User -> PhoneInput-Component.CountrySelect: "1. 国を選択"
+PhoneInput-Component.CountrySelect -> Form-State: "2. 'countryFieldName' の値を更新"
+
+User -> PhoneInput-Component.Phone-Field: "3. 電話番号を入力"
+PhoneInput-Component.Phone-Field -> Form-State: "4. 'name' の値（電話番号）を更新"
+
+Form-State -> PhoneInput-Component: "5. 状態を同期"
+```
+
+## Props
+
+`PhoneInput`コンポーネントは、すべての標準的なMaterial-UIの`TextField` propsに加えて、以下の特定のpropsを受け入れます：
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | `string` | Yes | - | `react-hook-form`に電話番号を登録するためのフィールド名。 |
+| `countryFieldName` | `string` | No | `'billing_address.country'` | 選択された国のISO2コードを保存するフォームフィールドの名前。これにより、電話番号入力の国を、アドレスコンポーネントなど、フォームの他の部分と同期させることができます。 |
+
+## 使用方法
+
+`PhoneInput`コンポーネントを使用するには、`react-hook-form`の`FormProvider`でラップする必要があります。次の例は、検証機能を含む基本的な実装を示しています。
+
+まず、ライブラリが提供する非同期検証関数が必要です。
+
+```javascript phone-validator.js icon=logos:javascript
+// src/libs/phone-validator.js
+import { getPhoneUtil } from '@blocklet/payment-react/libs/phone-validator';
+
+export const validatePhoneNumber = async (phoneNumber) => {
+  if (!phoneNumber) return true;
+  try {
+    const util = await getPhoneUtil();
+    const parsed = util.parseAndKeepRawInput(phoneNumber);
+    return util.isValidNumber(parsed);
+  } catch (err) {
+    console.error('Phone validation error:', err);
+    // ライブラリの読み込みに失敗した場合、単純な正規表現にフォールバックします
+    const pattern = /^[+]?[(]?[0-9]{3}[)]?[-\s.]?[0-9]{3}[-\s.]?[0-9]{4,6}$/im;
+    return pattern.test(phoneNumber) || 'Invalid phone number';
+  }
+};
+```
+
+これで、このバリデータをフォームコンポーネントで使用できます。
+
+```jsx MyPaymentForm.tsx icon=logos:react
+import { FormProvider, useForm } from 'react-hook-form';
+import { Button, Box } from '@mui/material';
+import { PhoneInput } from '@blocklet/payment-react';
+import { validatePhoneNumber } from '../libs/phone-validator'; // 必要に応じてパスを調整してください
+
+export default function MyPaymentForm() {
+  const methods = useForm({
+    mode: 'onBlur',
+    defaultValues: {
+      phone: '',
+      'billing_address.country': 'us', // デフォルトの国
+    },
+  });
+
+  const onSubmit = (data) => {
+    alert(JSON.stringify(data, null, 2));
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Box display="flex" flexDirection="column" gap={2}>
+          <PhoneInput
+            label="Phone Number"
+            name="phone"
+            // フォームの状態にある国フィールドへのリンク
+            countryFieldName="billing_address.country"
+            // 検証ルールを追加
+            rules={{
+              validate: async (value) => {
+                const isValid = await validatePhoneNumber(value);
+                return isValid || 'Please enter a valid phone number.';
+              },
+            }}
+            fullWidth
+          />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+        </Box>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+### 解説
+
+1.  **`FormProvider`**: `PhoneInput`を含むフォーム全体が`FormProvider`でラップされ、必要なフォームコンテキストを提供します。
+2.  **`name="phone"`**: これにより、入力フィールドがフォームデータ内で`phone`という名前で登録されます。
+3.  **`countryFieldName="billing_address.country"`**: これは`PhoneInput`に、フォームの状態にある`billing_address.country`フィールドの読み書きを両方行うように指示します。これにより同期が保たれます。このフィールドのデフォルト値は`useForm`で`'us'`に設定されています。
+4.  **`rules`**: 非同期の`validate`関数を`rules` propに渡します。`react-hook-form`は検証中にこの関数が解決されるのを待ちます。チェックを実行するために`validatePhoneNumber`ユーティリティが呼び出されます。
+
+## AddressFormとの統合
+
+`PhoneInput`の真価は、`AddressForm`と併用することで発揮されます。両方のコンポーネントは同じ国フィールド（デフォルトでは`billing_address.country`）にリンクできるため、`AddressForm`で国を変更すると、`PhoneInput`の国旗と国番号が自動的に更新されます。
+
+この統合の完全な例については、[`AddressForm`](./components-ui-form-elements-address-form.md)のドキュメントを参照してください。

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

@@ -0,0 +1,138 @@
+# PhoneInput
+
+`PhoneInput` 元件提供了一個使用者友善的國際電話號碼輸入欄位。它與 `react-hook-form` 無縫整合，並包含一個帶有國旗和國碼的可搜尋國家選擇器、自動號碼格式化，以及由 `google-libphonenumber` 支援的強大驗證功能。
+
+此元件旨在與其他表單元素（例如 [`CountrySelect`](./components-ui-form-elements-country-select.md) 或 [`AddressForm`](./components-ui-form-elements-address-form.md)）協同工作，透過將其選定的國家與共享的表單欄位同步。
+
+## 運作方式
+
+該元件利用 `react-international-phone` 函式庫實現其核心功能，並將其包裝以提供與 `react-hook-form` 和 Material-UI 的深度整合。當使用者選擇一個國家或輸入號碼時，該元件會更新表單狀態中對應的欄位。當另一個元件修改表單中連結的國家欄位時，它也會自動更新其國家選擇。
+
+```d2
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Form-State: {
+  label: "React Hook Form 狀態"
+  shape: cylinder
+}
+
+PhoneInput-Component: {
+  label: "PhoneInput 元件"
+
+  CountrySelect: {
+    label: "CountrySelect"
+  }
+
+  Phone-Field: {
+    label: "電話文字欄位"
+  }
+}
+
+User -> PhoneInput-Component.CountrySelect: "1. 選擇一個國家"
+PhoneInput-Component.CountrySelect -> Form-State: "2. 更新 'countryFieldName' 的值"
+
+User -> PhoneInput-Component.Phone-Field: "3. 輸入電話號碼"
+PhoneInput-Component.Phone-Field -> Form-State: "4. 更新 'name' 的值（電話號碼）"
+
+Form-State -> PhoneInput-Component: "5. 同步狀態"
+```
+
+## 屬性
+
+`PhoneInput` 元件接受所有標準的 Material-UI `TextField` 屬性，此外還包括以下特定屬性：
+
+| 屬性 | 類型 | 是否必須 | 預設值 | 描述 |
+|---|---|---|---|---|
+| `name` | `string` | 是 | - | 用於向 `react-hook-form` 註冊電話號碼的欄位名稱。 |
+| `countryFieldName` | `string` | 否 | `'billing_address.country'` | 儲存所選國家 ISO2 代碼的表單欄位名稱。這使得電話輸入的國家可以與表單的其他部分（例如地址元件）同步。 |
+
+## 使用方式
+
+若要使用 `PhoneInput` 元件，您必須將其包裝在 `react-hook-form` 的 `FormProvider` 中。以下範例展示了一個包含驗證的基本實作。
+
+首先，您需要函式庫提供的非同步驗證函式。
+
+```javascript phone-validator.js icon=logos:javascript
+// src/libs/phone-validator.js
+import { getPhoneUtil } from '@blocklet/payment-react/libs/phone-validator';
+
+export const validatePhoneNumber = async (phoneNumber) => {
+  if (!phoneNumber) return true;
+  try {
+    const util = await getPhoneUtil();
+    const parsed = util.parseAndKeepRawInput(phoneNumber);
+    return util.isValidNumber(parsed);
+  } catch (err) {
+    console.error('Phone validation error:', err);
+    // 如果函式庫載入失敗，則退回使用簡單的正規表示式
+    const pattern = /^[+]?[(]?[0-9]{3}[)]?[-\s.]?[0-9]{3}[-\s.]?[0-9]{4,6}$/im;
+    return pattern.test(phoneNumber) || 'Invalid phone number';
+  }
+};
+```
+
+現在，您可以在您的表單元件中使用此驗證器。
+
+```jsx MyPaymentForm.tsx icon=logos:react
+import { FormProvider, useForm } from 'react-hook-form';
+import { Button, Box } from '@mui/material';
+import { PhoneInput } from '@blocklet/payment-react';
+import { validatePhoneNumber } from '../libs/phone-validator'; // 根據需要調整路徑
+
+export default function MyPaymentForm() {
+  const methods = useForm({
+    mode: 'onBlur',
+    defaultValues: {
+      phone: '',
+      'billing_address.country': 'us', // 預設國家
+    },
+  });
+
+  const onSubmit = (data) => {
+    alert(JSON.stringify(data, null, 2));
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Box display="flex" flexDirection="column" gap={2}>
+          <PhoneInput
+            label="Phone Number"
+            name="phone"
+            // 連結到表單狀態中的國家欄位
+            countryFieldName="billing_address.country"
+            // 新增驗證規則
+            rules={{
+              validate: async (value) => {
+                const isValid = await validatePhoneNumber(value);
+                return isValid || 'Please enter a valid phone number.';
+              },
+            }}
+            fullWidth
+          />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+        </Box>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+### 解釋
+
+1.  **`FormProvider`**：整個表單，包括 `PhoneInput`，都被包裝在 `FormProvider` 中，以提供必要的表單情境。
+2.  **`name="phone"`**：這會將輸入欄位以 `phone` 的名稱註冊到表單資料中。
+3.  **`countryFieldName="billing_address.country"`**：這會告知 `PhoneInput` 從表單狀態的 `billing_address.country` 欄位讀取和寫入。這就是它保持同步的方式。在 `useForm` 中，此欄位的預設值被設為 `'us'`。
+4.  **`rules`**：我們將一個非同步的 `validate` 函式傳遞給 `rules` 屬性。`react-hook-form` 在驗證期間將會等待此函式解析完成。`validatePhoneNumber` 公用程式被呼叫以執行檢查。
+
+## 與 AddressForm 整合
+
+`PhoneInput` 的真正強大之處在於與 `AddressForm` 一同使用時才能展現。由於兩個元件可以連結到同一個國家欄位（預設為 `billing_address.country`），因此在 `AddressForm` 中變更國家將會自動更新 `PhoneInput` 中的國旗和國碼。
+
+關於此整合的完整範例，請參閱 [`AddressForm`](./components-ui-form-elements-address-form.md) 的文件。

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

@@ -0,0 +1,139 @@
+# PhoneInput
+
+`PhoneInput` 组件提供了一个用户友好的国际电话号码输入字段。它与 `react-hook-form` 无缝集成，并包含一个带有国旗和拨号代码的可搜索国家选择器、自动号码格式化以及由 `google-libphonenumber` 提供支持的强大验证功能。
+
+该组件旨在与其他表单元素（例如 [`CountrySelect`](./components-ui-form-elements-country-select.md) 或 [`AddressForm`](./components-ui-form-elements-address-form.md)）协同工作，通过与共享的表单字段同步其所选国家来实现。
+
+## 工作原理
+
+该组件利用 `react-international-phone` 库实现其核心功能，并对其进行包装，以提供与 `react-hook-form` 和 Material-UI 的深度集成。当用户选择一个国家或输入一个号码时，该组件会更新表单状态中相应的字段。当另一个组件修改表单中链接的国家字段时，它也会自动更新其国家选择。
+
+```d2
+direction: down
+
+User: {
+  label: "用户"
+  shape: c4-person
+}
+
+Form-State: {
+  label: "React Hook Form 状态"
+  shape: cylinder
+}
+
+PhoneInput-Component: {
+  label: "PhoneInput 组件"
+
+  CountrySelect: {
+    label: "CountrySelect"
+  }
+
+  Phone-Field: {
+    label: "电话文本字段"
+  }
+}
+
+User -> PhoneInput-Component.CountrySelect: "1. 选择一个国家"
+PhoneInput-Component.CountrySelect -> Form-State: "2. 更新 'countryFieldName' 的值"
+
+User -> PhoneInput-Component.Phone-Field: "3. 输入电话号码"
+PhoneInput-Component.Phone-Field -> Form-State: "4. 更新 'name' 的值（电话号码）"
+
+Form-State -> PhoneInput-Component: "5. 同步状态"
+```
+
+## Props
+
+`PhoneInput` 组件接受所有标准的 Material-UI `TextField` props，以及以下特定 props：
+
+| Prop | 类型 | 必需 | 默认值 | 描述 |
+|---|---|---|---|---|
+| `name` | `string` | 是 | - | 用于在 `react-hook-form` 中注册电话号码的字段名称。 |
+| `countryFieldName` | `string` | 否 | `'billing_address.country'` | 存储所选国家 ISO2 代码的表单字段的名称。这使得电话输入的国家可以与表单的其他部分（例如地址组件）同步。 |
+
+## 用法
+
+要使用 `PhoneInput` 组件，您必须将其包装在 `react-hook-form` 的 `FormProvider` 中。以下示例演示了带验证的基本实现。
+
+首先，您需要库提供的异步验证函数。
+
+```javascript phone-validator.js icon=logos:javascript
+// src/libs/phone-validator.js
+import { getPhoneUtil } from '@blocklet/payment-react/libs/phone-validator';
+
+export const validatePhoneNumber = async (phoneNumber) => {
+  if (!phoneNumber) return true;
+  try {
+    const util = await getPhoneUtil();
+    const parsed = util.parseAndKeepRawInput(phoneNumber);
+    return util.isValidNumber(parsed);
+  } catch (err) {
+    console.error('电话验证错误:', err);
+    // 如果库加载失败，则回退到简单的正则表达式
+    const pattern = /^[+]?[(]?[0-9]{3}[)]?[-\s.]?[0-9]{3}[-\s.]?[0-9]{4,6}$/im;
+    return pattern.test(phoneNumber) || '无效的电话号码';
+  }
+};
+```
+
+现在，您可以在表单组件中使用此验证器。
+
+```jsx MyPaymentForm.tsx icon=logos:react
+import { FormProvider, useForm } from 'react-hook-form';
+import { Button, Box } from '@mui/material';
+import { PhoneInput } from '@blocklet/payment-react';
+import { validatePhoneNumber } from '../libs/phone-validator'; // 根据需要调整路径
+
+export default function MyPaymentForm() {
+  const methods = useForm({
+    mode: 'onBlur',
+    defaultValues: {
+      phone: '',
+      'billing_address.country': 'us', // 默认国家
+    },
+  });
+
+  const onSubmit = (data) => {
+    alert(JSON.stringify(data, null, 2));
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Box display="flex" flexDirection="column" gap={2}>
+          <PhoneInput
+            label="Phone Number"
+            name="phone"
+            // 链接到表单状态中的国家字段
+            countryFieldName="billing_address.country"
+            // 添加验证规则
+            rules={{
+              validate: async (value) => {
+                const isValid = await validatePhoneNumber(value);
+                return isValid || '请输入有效的电话号码。';
+              },
+            }}
+            fullWidth
+          />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+        </Box>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+### 说明
+
+1.  **`FormProvider`**：整个表单（包括 `PhoneInput`）都包装在 `FormProvider` 中，以提供必要的表单上下文。
+2.  **`name="phone"`**：这会将输入字段以 `phone` 的名称注册到表单数据中。
+3.  **`countryFieldName="billing_address.country"`**：这告诉 `PhoneInput` 从表单状态的 `billing_address.country` 字段读取数据并向其写入数据。这就是它保持同步的方式。在 `useForm` 中，此字段的默认值设置为 `'us'`。
+4.  **`rules`**：我们将一个异步的 `validate` 函数传递给 `rules` prop。`react-hook-form` 将在验证期间等待此函数解析。调用 `validatePhoneNumber` 实用程序来执行检查。
+
+## 与 AddressForm 集成
+
+当 `PhoneInput` 与 `AddressForm` 一起使用时，其真正的强大之处就显现出来了。由于两个组件都可以链接到同一个国家字段（默认为 `billing_address.country`），因此在 `AddressForm` 中更改国家将自动更新 `PhoneInput` 中的国旗和拨号代码。
+
+有关此集成的完整示例，请参阅 [`AddressForm`](./components-ui-form-elements-address-form.md) 的文档。

package/docs/components-ui-form-elements.ja.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">
+    国旗付きでモバイルフレンドリーなUIを備えた、国を選択するための検索可能なドロップダウン。
+  </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';
+
+// Assume `availableCurrencies` is fetched from your backend
+const availableCurrencies = [
+  {
+    id: 'usd_xxx',
+    name: 'USD',
+    symbol: 'USD',
+    logo: 'url/to/usd_logo.png',
+    method: { id: 'stripe', name: 'Stripe' },
+  },
+  // ... other currencies
+];
+
+function MyCustomForm() {
+  const methods = useForm({
+    defaultValues: {
+      currency: 'usd_xxx',
+      phone_number: '',
+      billing_address: {
+        line1: '',
+        city: '',
+        state: '',
+        postal_code: '',
+        country: 'US', // Use ISO2 code
+      },
+    },
+  });
+
+  const onSubmit = (data) => {
+    console.log('Form data submitted:', 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-form-elements.zh-TW.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="電話號碼" required />
+          <AddressForm mode="required" stripe={false} />
+          <Button type="submit" variant="contained">
+            提交
+          </Button>
+        </Stack>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+在此範例中，`CurrencySelector`、`PhoneInput` 和 `AddressForm` 被組合在一個表單中。`CurrencySelector` 被用作一個與表單狀態綁定的受控元件，而 `PhoneInput` 和 `AddressForm` 則是非受控元件，它們會自動將其欄位和驗證規則註冊到 `react-hook-form` 的上下文中。
+
+## 後續步驟
+
+要了解每個元件的具體屬性和實作細節，請探索它們各自的說明文件頁面。
+
+從 [AddressForm](./components-ui-form-elements-address-form.md) 開始，了解如何收集帳單資訊。