@blocklet/payment-react 1.20.5 → 1.20.6

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

@@ -1,105 +1,126 @@
 # CountrySelect
 
-The `CountrySelect` component is a dropdown for selecting a country, featuring an integrated search filter, country flags, and a responsive design that adapts to desktop and mobile views. It is built to work seamlessly within forms managed by `react-hook-form` and must be wrapped in a `FormProvider` to function correctly.
+The `CountrySelect` component provides a user-friendly dropdown for selecting a country. It features a searchable list, displays country flags, and offers a responsive design that adapts to both desktop and mobile viewports. It is designed to be used within a form managed by `react-hook-form`.
 
 ## Props
 
-The component accepts the following props:
-
-| Prop | Type | Required | Default | Description |
-| :--- | :--- | :--- | :--- | :--- |
-| `value` | `CountryIso2` | Yes | | The ISO2 code of the currently selected country (e.g., 'us'). |
-| `onChange` | `(value: CountryIso2) => void` | Yes | | Callback function invoked when a country is selected. |
-| `name` | `string` | Yes | | The name of the input field, used for integration with `react-hook-form`. |
-| `sx` | `SxProps` | No | `{}` | Custom styles applied to the root element using the MUI `sx` prop. |
-| `showDialCode` | `boolean` | No | `false` | If `true`, the country's dial code is displayed next to its name in the list. |
+| Prop         | Type                             | Description                                                                                 | Required | Default |
+|--------------|----------------------------------|---------------------------------------------------------------------------------------------|----------|---------|
+| `value`      | `CountryIso2`                    | The ISO2 code of the selected country (e.g., 'us').                                         | Yes      |         |
+| `onChange`   | `(value: CountryIso2) => void`   | A callback function that is invoked when a country is selected.                             | Yes      |         |
+| `name`       | `string`                         | The name attribute for the input, used for integration with `react-hook-form`.              | Yes      |         |
+| `sx`         | `SxProps`                        | Custom styles to be applied to the root element.                                            | No       | `{}`    |
+| `showDialCode` | `boolean`                        | If `true`, the country's dial code will be displayed alongside its name in the list.        | No       | `false` |
 
 ## Basic Usage
 
-Here is a basic example of how to use the `CountrySelect` component. It must be wrapped in a `FormProvider` from `react-hook-form` because it internally uses `useFormContext` to manage form state.
+To use the `CountrySelect` component, you must wrap it in a `FormProvider` from `react-hook-form`. The component's state should be managed through the form context.
 
-```jsx
-import { useState } from 'react';
+```tsx Basic CountrySelect Example icon=logos:react
 import { FormProvider, useForm } from 'react-hook-form';
-import { CountrySelect } from '@blocklet/payment-react';
-import { Box } from '@mui/material';
+import { Box, Button, Typography } from '@mui/material';
+import CountrySelect from '@blocklet/payment-react/src/components/country-select'; // Adjust path as needed
 import type { CountryIso2 } from 'react-international-phone';
 
-function BasicCountrySelect() {
-  const [selectedCountry, setSelectedCountry] = useState<CountryIso2>('us');
-  const methods = useForm({
+export default function BasicCountrySelect() {
+  const methods = useForm<{ country: CountryIso2 }>({
     defaultValues: {
       country: 'us',
     },
   });
 
-  const handleCountryChange = (country: CountryIso2) => {
-    setSelectedCountry(country);
-    console.log('Selected Country:', country);
+  const { handleSubmit, watch, setValue } = methods;
+  const countryValue = watch('country'); // Watch for changes to update the controlled component
+
+  const onSubmit = (data: { country: CountryIso2 }) => {
+    alert(`Form submitted with country: ${data.country}`);
   };
 
   return (
     <FormProvider {...methods}>
-      <Box sx={{ maxWidth: 300 }}>
-        <CountrySelect
-          name="country"
-          value={selectedCountry}
-          onChange={handleCountryChange}
-        />
-      </Box>
+      <form onSubmit={handleSubmit(onSubmit)}>
+        <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, maxWidth: 400 }}>
+          <Typography variant="h6">Select Your Country</Typography>
+          <CountrySelect
+            name="country"
+            value={countryValue}
+            onChange={(newCountry) => {
+              setValue('country', newCountry, { shouldValidate: true });
+            }}
+          />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+          <Typography>
+            Current form value: {countryValue}
+          </Typography>
+        </Box>
+      </form>
     </FormProvider>
   );
 }
-
-export default BasicCountrySelect;
 ```
 
 ## Features
 
-### Search and Filtering
-The dropdown includes a search field at the top of the list, allowing users to filter countries by name, two-letter ISO code, or dial code (e.g., `+1`). This makes it easy to find a specific country in the extensive list.
+### Search and Filter
+The component includes a search bar at the top of the dropdown list, allowing users to quickly find a country by its name, ISO2 code, or dial code. For example, searching for "+1" will show the United States and Canada.
 
-### Responsive Design
-The component automatically adapts its UI based on the viewport. On desktop devices, it renders as a traditional dropdown menu. On mobile devices, it presents a full-width bottom-sheet dialog, providing a more native and touch-friendly user experience.
+### Responsive UI
+On desktop devices, `CountrySelect` renders as a standard dropdown menu. On mobile, it transforms into a full-width dialog that slides up from the bottom of the screen, providing an optimized user experience on smaller devices.
 
 ### Keyboard Accessibility
-`CountrySelect` is fully navigable using the keyboard, enhancing accessibility:
-- **ArrowDown / ArrowUp / Tab**: Navigate through the list of countries.
-- **Enter**: Select the currently focused country and close the dropdown.
-- **Escape**: Close the dropdown without making a selection.
+`CountrySelect` supports full keyboard navigation. Users can use the `ArrowUp` and `ArrowDown` keys to navigate the list, `Enter` to select a country, and `Escape` to close the dropdown. `Tab` and `Shift+Tab` also cycle through the list items.
 
-## Customization
+### Form Integration
+Designed to work seamlessly with `react-hook-form`. It automatically updates the form state when a selection is made, requiring it to be wrapped within a `FormProvider`.
 
-### Displaying the Dial Code
+## Advanced Usage
 
-To display the phone dial code next to each country, set the `showDialCode` prop to `true`. This is particularly useful when pairing `CountrySelect` with the [`PhoneInput`](./components-ui-form-elements-phone-input.md) component to build a complete international phone number input.
+### Displaying Dial Codes
 
-```jsx
-import { useState } from 'react';
+You can display the telephone dial code for each country in the list by setting the `showDialCode` prop to `true`.
+
+```tsx CountrySelect with Dial Code icon=logos:react
 import { FormProvider, useForm } from 'react-hook-form';
-import { CountrySelect } from '@blocklet/payment-react';
-import { Box } from '@mui/material';
+import { Box, Button } from '@mui/material';
+import CountrySelect from '@blocklet/payment-react/src/components/country-select'; // Adjust path as needed
 import type { CountryIso2 } from 'react-international-phone';
 
-function CountrySelectWithDialCode() {
-  const [country, setCountry] = useState<CountryIso2>('us');
-  const methods = useForm({ defaultValues: { country: 'us' } });
+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(`Form submitted with country: ${data.country}`);
+  };
 
   return (
     <FormProvider {...methods}>
-      <Box sx={{ maxWidth: 300 }}>
-        <CountrySelect
-          name="country"
-          value={country}
-          onChange={setCountry}
-          showDialCode={true}
-        />
-      </Box>
+      <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">
+            Submit
+          </Button>
+        </Box>
+      </form>
     </FormProvider>
   );
 }
-
-export default CountrySelectWithDialCode;
 ```
 
-By combining these features, the `CountrySelect` component offers a robust and user-friendly solution for country input fields in any form.
+## Next Steps
+
+This component is a building block for more complex form elements. See how it's integrated into the [PhoneInput](./components-ui-form-elements-phone-input.md) component to create a complete international phone number field.

package/docs/components-ui-form-elements-currency-selector.md

@@ -1,124 +1,108 @@
 # CurrencySelector
 
-The `CurrencySelector` component renders an interactive list of available payment currencies. Each currency is displayed as a distinct card, showing its logo, symbol, and the associated payment network, allowing users to easily choose their preferred option.
-
-This component is a form element designed to be integrated into broader payment flows, such as within a `CheckoutForm` or a custom payment UI.
+The `CurrencySelector` component provides a user-friendly interface for selecting a payment currency from a list of available options. It displays each currency with its logo, symbol, and associated payment method, making it easy for users to make a choice. This component is typically used within a larger payment or checkout form.
 
 ## Props
 
-The `CurrencySelector` component accepts the following props:
-
-| Prop         | Type                                                   | Description                                                                                                                              | Required |
-| :----------- | :----------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | :------- |
-| `value`      | `string`                                               | The `id` of the currently selected currency. This prop controls which currency card is highlighted with a checked radio button.          | Yes      |
-| `currencies` | `TPaymentCurrency[]`                                   | An array of currency objects to display as selectable options. See the `TPaymentCurrency` interface below for the required object structure. | Yes      |
-| `onChange`   | `(currencyId: string, methodId?: string) => void` | A callback function that fires when the user selects a currency. It receives the `id` of the chosen currency and its associated method.    | Yes      |
-
-### `TPaymentCurrency` Interface
-
-The `currencies` prop requires an array of objects, where each object represents a selectable currency and must conform to the following structure:
-
-```typescript
-interface TPaymentCurrency {
-  id: string;        // Unique identifier for the currency option
-  logo: string;      // URL to the currency or payment method logo
-  name: string;      // The display name of the currency
-  symbol: string;    // The currency symbol or ticker (e.g., "USDT", "BTC")
-  method: {
-    id: string;      // ID of the associated payment method or network
-    name: string;    // Display name of the associated payment method or network (e.g., "TRON Network")
+| Prop         | Type                                                     | Description                                                                                                       | Required |
+| :----------- | :------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | :------- |
+| `value`      | `string`                                                 | The ID of the currently selected currency. This should be managed by the parent component's state.              | Yes      |
+| `currencies` | `TPaymentCurrency[]`                                     | An array of available currency objects to display as selectable options.                                          | Yes      |
+| `onChange`   | `(currencyId: string, methodId?: string) => void`        | Callback function that is executed when a user selects a currency. It receives the new currency ID and the optional associated payment method ID. | Yes      |
+
+### TPaymentCurrency Type
+
+The `currencies` prop expects an array of objects with the following structure:
+
+```typescript TPaymentCurrency icon=mdi:code-json
+export type TPaymentCurrency = {
+  id: string;       // Unique identifier for the currency option
+  logo: string;     // URL for the currency/method logo
+  name: string;     // Display name for the currency
+  symbol: string;   // Currency symbol (e.g., '$', '€')
+  method: {         // Associated payment method
+    id: string;
+    name: string;
   };
-}
+};
 ```
 
-## Example Usage
+## Usage Example
 
-Below is an example of how to implement the `CurrencySelector`. It uses the `useState` hook to manage the user's selection and updates the UI accordingly. 
+Here is a basic example of how to implement the `CurrencySelector` component. You need to manage the selected currency's state in the parent component and provide a list of available currencies.
 
-Note that while `CurrencySelector` is a UI component, it's designed to function within a payment context. Therefore, it must be wrapped in `PaymentProvider`. For details on how to set up your session context, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+Note that `@blocklet/payment-react` components are designed to work within a `PaymentProvider`, which supplies the necessary theme and context. Ensure your component is wrapped accordingly.
 
-```tsx
+```jsx MyCurrencySelectorComponent.tsx icon=logos:react
 import React, { useState } from 'react';
-import { CurrencySelector, PaymentProvider } from '@blocklet/payment-react';
-import { useSessionContext } from '../hooks/session'; // Assuming a local session context hook
+import { PaymentProvider } from '@blocklet/payment-react';
+import { CurrencySelector } from '@blocklet/payment-react/components';
 import type { TPaymentCurrency } from '@blocklet/payment-types';
-import { Box, Typography, CircularProgress } from '@mui/material';
+import { useSessionContext } from '@/hooks/session-context'; // Adjust this import path to your project structure
 
-// Mock data representing available currencies
+// Mock data for demonstration purposes
 const mockCurrencies: TPaymentCurrency[] = [
   {
-    id: 'usdt_tron',
-    logo: 'https://cdn.jsdelivr.net/gh/atomiclabs/cryptocurrency-icons@1a63530be6e374711a8554f31b17e4cb92c25661/svg/color/usdt.svg',
-    name: 'Tether',
-    symbol: 'USDT',
-    method: {
-      id: 'tron_network',
-      name: 'TRON Network',
-    },
-  },
-  {
-    id: 'btc_native',
-    logo: 'https://cdn.jsdelivr.net/gh/atomiclabs/cryptocurrency-icons@1a63530be6e374711a8554f31b17e4cb92c25661/svg/color/btc.svg',
-    name: 'Bitcoin',
-    symbol: 'BTC',
+    id: 'usd_xxxxxx',
+    logo: 'https://path-to-your/usd-logo.png',
+    name: 'US Dollar',
+    symbol: 'USD',
     method: {
-      id: 'bitcoin_network',
-      name: 'Bitcoin Network',
+      id: 'stripe_yyyyy',
+      name: 'Stripe',
     },
   },
   {
-    id: 'eth_native',
-    logo: 'https://cdn.jsdelivr.net/gh/atomiclabs/cryptocurrency-icons@1a63530be6e374711a8554f31b17e4cb92c25661/svg/color/eth.svg',
+    id: 'eth_zzzzzz',
+    logo: 'https://path-to-your/eth-logo.png',
     name: 'Ethereum',
     symbol: 'ETH',
     method: {
-      id: 'ethereum_network',
-      name: 'Ethereum Network',
+      id: 'crypto_aaaaa',
+      name: 'Crypto Payment',
     },
   },
 ];
 
-function CurrencySelectorExample() {
-  const [selectedCurrencyId, setSelectedCurrencyId] = useState<string>('usdt_tron');
+function MyCurrencySelectorComponent() {
+  const [selectedCurrency, setSelectedCurrency] = useState<string>(mockCurrencies[0].id);
 
   const handleCurrencyChange = (currencyId: string, methodId?: string) => {
-    console.log(`Selected Currency ID: ${currencyId}, Method ID: ${methodId}`);
-    setSelectedCurrencyId(currencyId);
+    console.log(`Selected currency: ${currencyId}, Method: ${methodId}`);
+    setSelectedCurrency(currencyId);
   };
 
   return (
-    <Box sx={{ padding: 2, border: '1px solid #ddd', borderRadius: '4px' }}>
-      <Typography variant="h6" gutterBottom>
-        Select Your Payment Currency
-      </Typography>
+    <div>
+      <h3>Select a Currency</h3>
       <CurrencySelector
-        value={selectedCurrencyId}
+        value={selectedCurrency}
         currencies={mockCurrencies}
         onChange={handleCurrencyChange}
       />
-      <Typography sx={{ marginTop: '20px' }}>
-        Current Selection: <strong>{selectedCurrencyId}</strong>
-      </Typography>
-    </Box>
+    </div>
   );
 }
 
-// Most components from this library must be wrapped in PaymentProvider.
-export default function MyPaymentPage() {
+// Your App's entry point
+export default function App() {
   const { session, connectApi } = useSessionContext();
 
-  // PaymentProvider requires session and connectApi.
-  // Ensure these are available before rendering.
   if (!session || !connectApi) {
-    return <CircularProgress />;
+    return <div>Loading...</div>;
   }
 
   return (
     <PaymentProvider session={session} connectApi={connectApi}>
-      <CurrencySelectorExample />
+      <MyCurrencySelectorComponent />
     </PaymentProvider>
   );
 }
 ```
 
-In this example, `selectedCurrencyId` holds the state for the chosen currency. When a user clicks a currency card, the `handleCurrencyChange` function is triggered, which updates the state. The `CurrencySelector` re-renders to visually reflect the new selection.
+In this example:
+1.  We define a `mockCurrencies` array that follows the `TPaymentCurrency` structure.
+2.  The `MyCurrencySelectorComponent` uses the `useState` hook to keep track of the `selectedCurrency`.
+3.  The `handleCurrencyChange` function updates the state when a new currency is selected and logs the new values.
+4.  The `CurrencySelector` is a controlled component, with its `value` and `onChange` props managed by the parent's state.
+5.  The entire component is wrapped in `PaymentProvider` to ensure proper rendering and access to the Material-UI theme used for styling.

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

@@ -1,160 +1,138 @@
 # PhoneInput
 
-The `PhoneInput` component provides a user-friendly field for entering international phone numbers. It integrates seamlessly with `react-hook-form` and includes a built-in, searchable country selector. It is designed to work in tandem with a country selection field, ensuring data consistency across your form.
+The `PhoneInput` component provides a user-friendly, international phone number input field. It integrates seamlessly with `react-hook-form` and includes a searchable country selector with flags and dial codes, automatic number formatting, and powerful validation powered by `google-libphonenumber`.
 
-### Features
+This component is designed to work in tandem with other form elements, such as the [`CountrySelect`](./components-ui-form-elements-country-select.md) or [`AddressForm`](./components-ui-form-elements-address-form.md), by synchronizing its selected country with a shared form field.
 
-- **React Hook Form Integration**: Built to work directly with `useFormContext` for easy state management and validation.
-- **Interactive Country Selector**: Includes the `CountrySelect` component as a prefix, offering country flags, names, and a search field.
-- **Two-Way Country Synchronization**: Automatically syncs the selected country with another form field (e.g., a billing address country field).
-- **Asynchronous Validation**: Leverages `google-libphonenumber` for robust validation without blocking the main thread on initial load.
-- **Responsive Design**: The country selector adapts to the viewport, using a dropdown on desktop and a dialog on mobile devices.
+## How It Works
+
+The component leverages the `react-international-phone` library for its core functionality and wraps it to provide deep integration with `react-hook-form` and Material-UI. When a user selects a country or types a number, the component updates the corresponding fields in the form state. It also automatically updates its country selection when another component modifies the linked country field in the form.
+
+```d2
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Form-State: {
+  label: "React Hook Form State"
+  shape: cylinder
+}
+
+PhoneInput-Component: {
+  label: "PhoneInput Component"
+
+  CountrySelect: {
+    label: "CountrySelect"
+  }
+
+  Phone-Field: {
+    label: "Phone Text Field"
+  }
+}
+
+User -> PhoneInput-Component.CountrySelect: "1. Selects a country"
+PhoneInput-Component.CountrySelect -> Form-State: "2. Updates 'countryFieldName' value"
+
+User -> PhoneInput-Component.Phone-Field: "3. Enters phone number"
+PhoneInput-Component.Phone-Field -> Form-State: "4. Updates 'name' value (phone number)"
+
+Form-State -> PhoneInput-Component: "5. Synchronizes state"
+```
 
 ## Props
 
-The `PhoneInput` component accepts all standard props from Material-UI's `TextField` in addition to its own specific props.
+The `PhoneInput` component accepts all standard Material-UI `TextField` props, in addition to the following specific props:
 
-| Prop | Type | Description | Default |
-| --- | --- | --- | --- |
-| `name` | `string` | **Required.** The name of the field to be registered with `react-hook-form`. | - |
-| `countryFieldName` | `string` | The name of the form field that stores the selected country's ISO 3166-1 alpha-2 code. The component synchronizes with this field. | `'billing_address.country'` |
-| `...rest` | `TextFieldProps` | Any other props accepted by the Material-UI `TextField` component, such as `label`, `placeholder`, `required`, `helperText`, and `error`. | - |
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | `string` | Yes | - | The name of the field to register with `react-hook-form` for the phone number. |
+| `countryFieldName` | `string` | No | `'billing_address.country'` | The name of the form field that stores the selected country's ISO2 code. This allows the phone input's country to be synchronized with other parts of your form, such as an address component. |
 
 ## Usage
 
-The `PhoneInput` must be wrapped in a `FormProvider` from `react-hook-form`. While it is often used within payment forms that require `PaymentProvider`, the component itself does not need it. For details on setting up the payment context, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
-
-### Basic Example
+To use the `PhoneInput` component, you must wrap it in a `FormProvider` from `react-hook-form`. The following example demonstrates a basic implementation with validation.
+
+First, you need the asynchronous validation function provided by the library.
+
+```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);
+    // Fallback to a simple regex if lib fails to load
+    const pattern = /^[+]?[(]?[0-9]{3}[)]?[-\s.]?[0-9]{3}[-\s.]?[0-9]{4,6}$/im;
+    return pattern.test(phoneNumber) || 'Invalid phone number';
+  }
+};
+```
 
-This example demonstrates a complete form with a `PhoneInput` and a separate `CountrySelect` for the billing address. The two are synchronized via the `countryFieldName` prop.
+Now, you can use this validator in your form component.
 
-```tsx
+```jsx MyPaymentForm.tsx icon=logos:react
 import { FormProvider, useForm } from 'react-hook-form';
-import { Button, Stack } from '@mui/material';
-import PhoneInput from '@blocklet/payment-react/components/ui/form-elements/phone-input';
-import CountrySelect from '@blocklet/payment-react/components/ui/form-elements/country-select';
-import { validatePhoneNumber } from '@blocklet/payment-react/libs/phone-validator';
+import { Button, Box } from '@mui/material';
+import { PhoneInput } from '@blocklet/payment-react';
+import { validatePhoneNumber } from '../libs/phone-validator'; // Adjust path as needed
 
-export default function PhoneForm() {
+export default function MyPaymentForm() {
   const methods = useForm({
-    mode: 'onBlur', // Validate on blur
+    mode: 'onBlur',
     defaultValues: {
       phone: '',
       'billing_address.country': 'us', // Default country
     },
   });
 
-  const { handleSubmit, formState: { errors }, watch, setValue, register } = methods;
-
   const onSubmit = (data) => {
     alert(JSON.stringify(data, null, 2));
   };
 
   return (
     <FormProvider {...methods}>
-      <form onSubmit={handleSubmit(onSubmit)}>
-        <Stack spacing={2}>
-          <CountrySelect
-            name="billing_address.country"
-            value={watch('billing_address.country')}
-            onChange={(country) => setValue('billing_address.country', country, { shouldValidate: true })}
-          />
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Box display="flex" flexDirection="column" gap={2}>
           <PhoneInput
             label="Phone Number"
             name="phone"
-            required
-            {...register('phone', {
-              required: 'Phone number is required.',
+            // Link to the country field in the form state
+            countryFieldName="billing_address.country"
+            // Add validation rules
+            rules={{
               validate: async (value) => {
                 const isValid = await validatePhoneNumber(value);
-                return isValid || 'Please enter a valid phone number';
+                return isValid || 'Please enter a valid phone number.';
               },
-            })}
-            error={!!errors.phone}
-            helperText={errors.phone?.message?.toString()}
+            }}
+            fullWidth
           />
           <Button type="submit" variant="contained">
             Submit
           </Button>
-        </Stack>
+        </Box>
       </form>
     </FormProvider>
   );
 }
 ```
 
-## Country Synchronization
-
-The key feature of `PhoneInput` is its ability to synchronize with an external country field. This is particularly useful in forms like an [AddressForm](./components-ui-form-elements-address-form.md) where the phone number's country should match the billing address country.
-
-- **Default Behavior**: By default, it listens to and updates a form field named `billing_address.country`.
-- **Customization**: You can specify a different field name by passing the `countryFieldName` prop.
+### Explanation
 
-This two-way synchronization works as follows:
-1.  When the user selects a country in an external `CountrySelect` component, the flag and dial code inside the `PhoneInput` update automatically.
-2.  When the user changes the country from the dropdown within the `PhoneInput`, the value of the `countryFieldName` field is also updated, ensuring the entire form state remains consistent.
+1.  **`FormProvider`**: The entire form, including the `PhoneInput`, is wrapped in a `FormProvider` to provide the necessary form context.
+2.  **`name="phone"`**: This registers the input field under the name `phone` in the form data.
+3.  **`countryFieldName="billing_address.country"`**: This tells `PhoneInput` to both read from and write to the `billing_address.country` field in the form's state. This is how it stays synchronized. The default value for this field is set to `'us'` in `useForm`.
+4.  **`rules`**: We pass an asynchronous `validate` function to the `rules` prop. `react-hook-form` will await this function to resolve during validation. The `validatePhoneNumber` utility is called to perform the check.
 
-The following diagram illustrates this interaction:
+## Integration with AddressForm
 
-```d2
-direction: down
-
-User: "User"
-
-UI: {
-  shape: package
-  "PhoneInput": {
-    "Internal CountrySelect": "Country selector inside phone input"
-  }
-  "External CountrySelect": "Separate country selector for address"
-}
-
-FormState: "react-hook-form State" {
-  shape: cylinder
-  phone: "Phone number value"
-  "billing_address.country": "Country ISO code"
-}
-
-User -> UI."External CountrySelect": "Selects 'Canada'"
-UI."External CountrySelect" -> FormState."billing_address.country": "Updates state to 'ca'"
-FormState."billing_address.country" -> UI."PhoneInput"."Internal CountrySelect": "Syncs flag and dial code to Canada"
-
-User -> UI."PhoneInput"."Internal CountrySelect": "Selects 'UK'"
-UI."PhoneInput"."Internal CountrySelect" -> FormState."billing_address.country": "Updates state to 'gb'"
-FormState."billing_address.country" -> UI."External CountrySelect": "Syncs selection to UK"
-```
-
-## Validation
-
-Phone number validation is handled by the `validatePhoneNumber` utility. This function asynchronously loads the `google-libphonenumber` library to perform validation without impacting your application's initial load time. If the library fails to load, it falls back to a basic regex pattern for validation.
-
-To apply validation, use the `validate` function in the rules object when registering the field with `react-hook-form`, as shown in the example above.
-
-## Helper Utilities
-
-### `formatPhone`
-
-The library also exports a `formatPhone` utility function that can be used to standardize a phone number into the E.164 international format (e.g., `+12125552368`). This is useful for normalizing data before sending it to your backend.
-
-**Parameters**
-
-| Parameter | Type | Description | Default |
-| --- | --- | --- | --- |
-| `phoneNumber` | `string` | The original phone number string. | - |
-| `defaultCountry` | `string` | The default country code (ISO 3166-1 alpha-2) to use if the number is ambiguous. | `'US'` |
-
-**Example**
-
-```javascript
-import { formatPhone } from '@blocklet/payment-react/libs/phone-validator';
-
-const rawNumber = '(541) 754-3010';
-const formattedNumber = formatPhone(rawNumber, 'US');
-// formattedNumber will be '+15417543010'
-
-const rawUkNumber = '07700 900077';
-const formattedUkNumber = formatPhone(rawUkNumber, 'GB');
-// formattedUkNumber will be '+447700900077'
-```
+The true power of `PhoneInput` is revealed when used alongside an `AddressForm`. Since both components can be linked to the same country field (`billing_address.country` by default), changing the country in the `AddressForm` will automatically update the flag and dial code in the `PhoneInput`.
 
-This utility is particularly helpful for normalizing phone numbers before submitting them to a backend service.
+For a complete example of this integration, please see the documentation for [`AddressForm`](./components-ui-form-elements-address-form.md).