@blocklet/payment-react 1.19.23 → 1.20.1

package/docs/components-history-credit-transactions-list.md

@@ -0,0 +1,116 @@
+# CreditTransactionsList
+
+The `CreditTransactionsList` component renders a detailed and paginated table of credit transactions. It serves as a comprehensive log, allowing users to track how their credits have been utilized or adjusted over time. This component is essential for providing transparency in credit-based billing systems.
+
+### Context Requirement
+
+This component requires access to the session context to identify the current user. Therefore, it must be rendered within a `PaymentProvider`. For details on setting up the provider and a `useSessionContext` hook, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+
+### Properties
+
+The `CreditTransactionsList` component accepts the following properties:
+
+| Prop | Type | Description | Default |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | The ID of the customer whose transactions are to be displayed. If omitted, it defaults to the DID of the currently logged-in user from the session context. | `session.user.did` |
+| `subscription_id` | `string` | Filters the transactions to show only those related to a specific subscription ID. | `''` |
+| `credit_grant_id` | `string` | Filters the transactions to show only those related to a specific credit grant ID. | `''` |
+| `pageSize` | `number` | The number of transactions to display per page. | `10` |
+| `onTableDataChange` | `(data, prevData) => void` | A callback function that is triggered when the transaction data is fetched or updated. It receives the new data and the previous data as arguments. | `() => {}` |
+| `showAdminColumns` | `boolean` | If `true`, additional columns relevant to administrators (such as 'Meter Event') are displayed. This only applies if the logged-in user has an 'owner' or 'admin' role. | `false` |
+| `showTimeFilter` | `boolean` | If `true`, a date range picker is displayed above the table, allowing users to filter transactions by a specific time period. | `false` |
+| `source` | `string` | An optional string to filter transactions by their source. | `''` |
+| `mode` | `'dashboard' \| 'portal'` | Controls the navigation behavior of links within the table. Use `'dashboard'` for admin-facing views and `'portal'` for standard customer-facing portals. | `'portal'` |
+
+### Usage Scenarios
+
+All examples assume you have a `useSessionContext` hook configured as outlined in the `PaymentProvider` guide.
+
+#### 1. Basic Customer View
+
+To display the credit transaction history for the currently logged-in user, you can render the component without any specific IDs. It will automatically fetch the user's data from the session context.
+
+```jsx
+import React from 'react';
+import { CreditTransactionsList } from '@blocklet/payment-react/components/history';
+// Assuming useSessionContext is set up according to the PaymentProvider guide
+import { useSessionContext } from '../../contexts/session';
+
+export default function UserCreditHistoryPage() {
+  const { session } = useSessionContext();
+
+  // Render the component only when the session is active
+  if (!session.user) {
+    return <p>Please log in to see your credit history.</p>;
+  }
+
+  return (
+    <>
+      <h2>My Credit Transactions</h2>
+      <CreditTransactionsList pageSize={5} />
+    </>
+  );
+}
+```
+
+#### 2. Admin View with Filters
+
+For an administrative dashboard, you can display transactions for a specific customer by providing their `customer_id`. You can also enable admin-specific columns and the date filter to provide more powerful data exploration tools.
+
+```jsx
+import React from 'react';
+import { CreditTransactionsList } from '@blocklet/payment-react/components/history';
+// Assuming useSessionContext is set up according to the PaymentProvider guide
+import { useSessionContext } from '../../contexts/session';
+
+export default function AdminCustomerCreditHistory({ customerId }) {
+  const { session } = useSessionContext();
+  const isAdmin = ['owner', 'admin'].includes(session?.user?.role || '');
+
+  if (!isAdmin) {
+    return <p>Access Denied.</p>;
+  }
+
+  return (
+    <>
+      <h2>Credit Transactions for Customer {customerId}</h2>
+      <CreditTransactionsList
+        customer_id={customerId}
+        showAdminColumns={true}
+        showTimeFilter={true}
+        mode="dashboard"
+      />
+    </>
+  );
+}
+```
+
+#### 3. Transactions for a Specific Credit Grant
+
+When you need to show a detailed usage report for a single credit grant, pass the `credit_grant_id`. This will filter the list to show only the transactions associated with that grant.
+
+```jsx
+import React from 'react';
+import { CreditTransactionsList } from '@blocklet/payment-react/components/history';
+
+export default function CreditGrantUsageDetails({ grantId }) {
+  return (
+    <>
+      <h3>Transaction History for this Grant</h3>
+      <CreditTransactionsList credit_grant_id={grantId} />
+    </>
+  );
+}
+```
+
+### Table Columns
+
+The component renders a table with the following columns:
+
+- **Amount**: The value of the credit transaction and its unit.
+- **Credit Grant**: A link to the parent credit grant. This column is automatically hidden if the list is already filtered by a `credit_grant_id`.
+- **Description**: Provides context for the transaction, such as the associated subscription or usage event.
+- **Meter Event** (Admin Only): A link to the specific billing meter event that triggered the transaction. This is only visible when `showAdminColumns` is `true` and the user is an admin.
+- **Date**: The timestamp indicating when the transaction was created.
+
+After displaying credit usage, you might want to show an overview of all credit grants. To do this, you can use the [`CreditGrantsList`](./components-history-credit-grants-list.md) component.

package/docs/components-history-invoice-list.md

@@ -0,0 +1,104 @@
+# CustomerInvoiceList
+
+The `CustomerInvoiceList` component renders a history of invoices for a specific customer or subscription. It supports two display formats: a compact list grouped by date (`list`) and a detailed, paginated table (`table`). The component can also display a 'Pay' button for open invoices, initiating the payment flow when clicked.
+
+To function correctly, especially for payment actions and real-time updates, this component must be wrapped within a `PaymentProvider`. For details on setting up the provider and the `useSessionContext` hook, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+
+## Props
+
+| Prop | Type | Description | Default |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | The ID of the customer whose invoices are to be displayed. | `''` |
+| `subscription_id` | `string` | The ID of the subscription for which to display invoices. | `''` |
+| `currency_id` | `string` | Filters invoices by a specific currency ID. | `''` |
+| `include_staking` | `boolean` | If `true`, includes staking-related invoices in the list. | `false` |
+| `include_return_staking` | `boolean` | If `true`, includes invoices for returned stakes. | `false` |
+| `include_recovered_from` | `boolean` | If `true`, includes invoices that were recovered from bad debt. | `false` |
+| `status` | `string` | A comma-separated string of invoice statuses to display (e.g., 'open,paid,uncollectible,void'). | `'open,paid,uncollectible'` |
+| `pageSize` | `number` | The number of invoices to display per page. | `10` |
+| `target` | `string` | The target attribute for invoice links (e.g., `_self`, `_blank`). | `'_self'` |
+| `action` | `string` | If set (e.g., to `'pay'`), a 'Pay' button is rendered for open or uncollectible invoices, triggering the payment flow on click. | `''` |
+| `type` | `'list'` \| `'table'` | Determines the rendering mode. `'list'` groups invoices by date, while `'table'` shows a detailed data grid. | `'list'` |
+| `onTableDataChange` | `(newData, oldData) => void` | A callback function that fires when the invoice data is loaded or refreshed. | `() => {}` |
+| `relatedSubscription` | `boolean` | When `type` is `'table'`, setting this to `true` adds a column showing the subscription related to each invoice. | `false` |
+
+## Usage Scenarios
+
+### Basic Invoice History
+
+To display a simple list of invoices for a particular subscription, set the `subscription_id` and use the default `type='list'`. This mode is ideal for a quick overview of past transactions.
+
+```tsx
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session'; // Your local session context hook
+
+function InvoiceHistoryPage({ subscriptionId }) {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <h2>Invoice History</h2>
+      <CustomerInvoiceList
+        subscription_id={subscriptionId}
+        status="paid,void"
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+### Detailed Invoice Table
+
+For a more detailed view, use `type='table'`. This mode provides pagination and multiple columns of data, making it suitable for dashboards or customer management pages. You can also add the `relatedSubscription` column for customers with multiple subscriptions.
+
+```tsx
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session'; // Your local session context hook
+
+function CustomerDashboard({ customerId }) {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <h3>All Invoices</h3>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        type="table"
+        pageSize={20}
+        include_staking={true}
+        relatedSubscription={true}
+        status="open,paid,uncollectible,void"
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+### Invoices with Payment Action
+
+By setting the `action` prop, you can enable a 'Pay' button for any invoices that are `open` or `uncollectible`. Clicking this button will open the payment modal provided by `PaymentProvider` to complete the transaction.
+
+```tsx
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session'; // Your local session context hook
+
+function PayInvoices({ customerId }) {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <h3>Outstanding Invoices</h3>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        status="open,uncollectible"
+        action="pay" // This enables the "Pay" button
+        type="table"
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+### Real-time Updates
+
+The component automatically subscribes to the `invoice.paid` WebSocket event. When a customer successfully pays an invoice, the list will refresh in real-time to reflect the new `paid` status without requiring a page reload. This ensures that the invoice data is always up-to-date.

package/docs/components-history-payment-list.md

@@ -0,0 +1,65 @@
+# CustomerPaymentList
+
+The `CustomerPaymentList` component renders a detailed history of a customer's payments. It is designed for efficiency, featuring infinite scrolling to handle large numbers of transactions without compromising performance. Payments are automatically grouped by date for easy navigation and review.
+
+## Props
+
+| Prop | Type | Description | Required |
+|---|---|---|---|
+| `customer_id` | `string` | The ID of the customer whose payment history should be displayed. | Yes |
+
+## Usage Example
+
+To use the `CustomerPaymentList`, you must provide a `customer_id`. The component handles all the logic for fetching, paginating, and displaying the payment data. It must be wrapped within a `PaymentProvider` to function correctly.
+
+```tsx
+import { PaymentProvider, CustomerPaymentList } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session'; // This is your app's custom session hook
+import { Box, Typography } from '@mui/material';
+
+function CustomerProfilePage() {
+  // Get session and connectApi from your application's session context.
+  const { session, connectApi } = useSessionContext();
+
+  // The customer ID would typically be the DID of the logged-in user.
+  const customerDid = session?.user?.did;
+
+  if (!session || !customerDid) {
+    return <Typography>Please log in to view payment history.</Typography>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <Box sx={{ p: 3 }}>
+        <Typography variant="h5" gutterBottom>
+          Payment History
+        </Typography>
+        <CustomerPaymentList customer_id={customerDid} />
+      </Box>
+    </PaymentProvider>
+  );
+}
+
+export default CustomerProfilePage;
+```
+
+In the example above, `useSessionContext` is a custom hook responsible for providing your application's session state. For detailed instructions on how to set up the `PaymentProvider` and create a session context, please refer to our guide on the [PaymentProvider](./providers-payment-provider.md).
+
+## Features
+
+- **Automatic Pagination**: The component automatically fetches and renders payments in pages. A "Load More" button appears when more transactions are available, allowing users to load history on demand.
+
+- **Date-Based Grouping**: To improve readability, all payments are grouped under the date they were created, making it easy to find transactions from a specific day.
+
+- **Detailed Payment Information**: Each row in the list provides key details about the transaction:
+  - **Date & Time**: The exact creation time of the payment.
+  - **Amount**: The total amount received, formatted with the correct currency symbol.
+  - **Status**: The current status of the payment (e.g., `succeeded`, `processing`) shown with a colored indicator using the `Status` component.
+  - **Description**: The description associated with the payment intent.
+  - **Transaction Link**: A direct link to the relevant blockchain explorer for on-chain transactions, if applicable.
+
+- **Loading and Empty States**: A loading indicator is displayed while the initial payment data is being fetched. If the customer has no payment history, a clear message is shown instead of an empty list.
+
+## Related Components
+
+For displaying a customer's invoice history, which is often related to their payment history, see the [`CustomerInvoiceList`](./components-history-invoice-list.md) component.

package/docs/components-history.md

@@ -0,0 +1,92 @@
+# History Components
+
+The History Components are a suite of tools designed to give customers a clear and detailed view of their financial interactions. They are essential for building transparent and user-friendly account management sections, such as a customer portal or a billing history page. These components fetch and display data related to invoices, payments, and credit balances, providing a complete historical record.
+
+```d2
+direction: down
+
+"Customer Portal" -> "Billing Section"
+
+"Billing Section": {
+  "Invoices": "CustomerInvoiceList"
+  "Payments": "CustomerPaymentList"
+  "Credits": {
+    "Grants": "CreditGrantsList"
+    "Usage": "CreditTransactionsList"
+  }
+}
+```
+
+This section provides an overview of the components available for displaying historical data. Each component is designed to be easily integrated into your application to provide a specific piece of a customer's history.
+
+<x-cards data-columns="2">
+  <x-card data-title="CustomerInvoiceList" data-icon="lucide:receipt" data-href="/components/history/invoice-list">
+    Renders a list of a customer's invoices, including key details like the amount, status, date, and a link to view the full invoice. It supports both a simple list view and a more detailed table view.
+  </x-card>
+  <x-card data-title="CustomerPaymentList" data-icon="lucide:credit-card" data-href="/components/history/payment-list">
+    Use this component to display a complete history of payments made by a customer. It lists each payment with its amount, status, date, and a link to the corresponding transaction on the blockchain, if applicable.
+  </x-card>
+  <x-card data-title="CreditGrantsList" data-icon="lucide:gift" data-href="/components/history/credit-grants-list">
+    The `CreditGrantsList` component shows all credit grants a customer has received. It details the status, remaining balance, and validity period of each grant, which is useful for managing promotional credits or prepaid balances.
+  </x-card>
+  <x-card data-title="CreditTransactionsList" data-icon="lucide:list-ordered" data-href="/components/history/credit-transactions-list">
+    To provide a granular view of how credits are used, the `CreditTransactionsList` component logs every transaction that affects a customer's credit balance. This includes credit deductions for service usage and any adjustments.
+  </x-card>
+</x-cards>
+
+### Example: Building a Billing Page
+
+You can easily combine these components using a tabbed interface to create a complete billing history section for your users. Most history components rely on `PaymentProvider` to access the DID Connect instance for actions like paying an invoice.
+
+The following example shows how to set up a complete billing page. It assumes you have a local `session.js` or `session.ts` file that exports `useSessionContext` for your DID Connect integration. For more details on setting up the provider, see the [PaymentProvider documentation](./providers-payment-provider.md).
+
+```jsx
+import React from 'react';
+import { Tabs, Tab, Box, Typography } from '@mui/material';
+import { PaymentProvider } from '@blocklet/payment-react/lib/contexts/payment';
+import { useSessionContext } from '../contexts/session'; // Your local session context
+
+import CustomerInvoiceList from '@blocklet/payment-react/lib/history/invoice/list';
+import CustomerPaymentList from '@blocklet/payment-react/lib/history/payment/list';
+import CreditGrantsList from '@blocklet/payment-react/lib/history/credit/grants-list';
+import CreditTransactionsList from '@blocklet/payment-react/lib/history/credit/transactions-list';
+
+function BillingHistoryPage() {
+  const { session, connect } = useSessionContext();
+  const [tab, setTab] = React.useState(0);
+
+  const handleChange = (event, newValue) => {
+    setTab(newValue);
+  };
+
+  // The customerId is the user's DID from the session.
+  const customerId = session.user?.did;
+
+  if (!session.ready || !customerId) {
+    return <Typography>Please log in to view your billing history.</Typography>;
+  }
+
+  return (
+    <PaymentProvider connect={connect}>
+      <Box sx={{ width: '100%' }}>
+        <Tabs value={tab} onChange={handleChange} aria-label="billing history tabs">
+          <Tab label="Invoices" />
+          <Tab label="Payments" />
+          <Tab label="Credit Grants" />
+          <Tab label="Credit Usage" />
+        </Tabs>
+        <Box sx={{ p: 3 }}>
+          {tab === 0 && <CustomerInvoiceList customer_id={customerId} type="table" />}
+          {tab === 1 && <CustomerPaymentList customer_id={customerId} />}
+          {tab === 2 && <CreditGrantsList customer_id={customerId} />}
+          {tab === 3 && <CreditTransactionsList customer_id={customerId} />}
+        </Box>
+      </Box>
+    </PaymentProvider>
+  );
+}
+```
+
+By using these components, you can build a comprehensive and professional billing history section. This not only improves user experience but also reduces support inquiries by providing customers with self-service access to their data.
+
+After implementing history views, you may want to explore advanced topics like customization and theming. Continue to the next section to learn more in our [Guides](./guides.md).

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

@@ -0,0 +1,150 @@
+# AddressForm
+
+The `AddressForm` component provides a pre-built UI for collecting billing address details. It includes fields for address line 1, city, state, postal code, and country, with built-in validation that adapts based on the selected country.
+
+This component is designed to work seamlessly within the context of `react-hook-form`.
+
+## Props
+
+| Prop | Type | Description | Required |
+| --- | --- | --- | :---: |
+| `mode` | `string` | Determines the form's behavior. Set to `'required'` to display the full address form. | Yes |
+| `stripe` | `boolean` | If `true` and `mode` is not `'required'`, it displays a simplified form with only postal code and country. | Yes |
+| `sx` | `SxProps` | Custom MUI styles to be applied to the root `Stack` component. | No |
+| `fieldValidation` | `Record<string, any>` | An object for providing custom validation rules, such as regex patterns, for specific fields. | No |
+| `errorPosition` | `'right'` \| `'bottom'` | Specifies the position of validation error messages relative to the input fields. Defaults to `'right'`. | No |
+
+## Integration with React Hook Form
+
+`AddressForm` uses `useFormContext` and therefore must be a descendant of a `FormProvider` component from `react-hook-form`. In a typical application, a higher-level component like `CheckoutForm` would wrap your feature and provide this context automatically. 
+
+Note: The following examples assume you have set up `PaymentProvider` and a local `useSessionContext` hook as described in the [PaymentProvider documentation](./providers-payment-provider.md).
+
+## Usage Scenarios
+
+### Complete Address Form
+
+To collect a full billing address, set the `mode` prop to `'required'`. This will render all address fields as mandatory.
+
+```jsx
+import { FormProvider, useForm } from 'react-hook-form';
+import { AddressForm } from '@blocklet/payment-react';
+import { Button, Stack } from '@mui/material';
+import { useSessionContext } from '../hooks/session'; // Adjust path to your session hook
+
+export default function FullAddressFormExample() {
+  // Standard context setup. Not used in this specific form but required for consistency.
+  const { session, connectApi } = useSessionContext();
+
+  const methods = useForm({
+    mode: 'onTouched',
+    defaultValues: {
+      billing_address: {
+        line1: '',
+        city: '',
+        state: '',
+        postal_code: '',
+        country: 'US',
+      },
+    },
+  });
+
+  const onSubmit = (data) => {
+    alert('Form Submitted! Check console for data.');
+    console.log('Billing Address:', data.billing_address);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Stack spacing={2}>
+          <AddressForm mode="required" stripe={false} errorPosition="bottom" />
+          <Button type="submit" variant="contained">
+            Submit Address
+          </Button>
+        </Stack>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+### Simplified Stripe Form
+
+In some payment flows, particularly with Stripe, only the postal code and country might be required for verification. To render this simplified version, ensure `mode` is not `'required'` and set the `stripe` prop to `true`.
+
+```jsx
+import { FormProvider, useForm } from 'react-hook-form';
+import { AddressForm } from '@blocklet/payment-react';
+import { Button, Stack } from '@mui/material';
+import { useSessionContext } from '../hooks/session'; // Adjust path to your session hook
+
+export default function StripeAddressFormExample() {
+  // Standard context setup. Not used in this specific form but required for consistency.
+  const { session, connectApi } = useSessionContext();
+
+  const methods = useForm({
+    mode: 'onTouched',
+    defaultValues: {
+      billing_address: {
+        postal_code: '',
+        country: 'US',
+      },
+    },
+  });
+
+  const onSubmit = (data) => {
+    alert('Form Submitted! Check console for data.');
+    console.log('Billing Info:', data.billing_address);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(onSubmit)}>
+        <Stack spacing={2}>
+          <AddressForm mode="optional" stripe={true} errorPosition="bottom" />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+        </Stack>
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+## Validation
+
+`AddressForm` handles validation for required fields automatically. It also includes special validation logic for postal codes.
+
+### Postal Code Validation
+
+The postal code field is dynamically validated based on the selected country. The component uses the `validator.js` library to check if the postal code format is valid for a list of supported countries. For countries not on the supported list, a generic validation is applied.
+
+### Custom Validation
+
+You can extend the default validation by passing a `fieldValidation` object. This allows you to specify custom regex patterns and error messages for any address field.
+
+For example, to add a pattern validation for the state field to accept only two-letter abbreviations:
+
+```jsx
+const customValidation = {
+  'billing_address.state': {
+    pattern: '^[A-Z]{2}$',
+    pattern_message: {
+      en: 'State must be a 2-letter abbreviation.',
+      // Add other locales as needed
+    },
+  },
+};
+
+<AddressForm
+  mode="required"
+  stripe={false}
+  fieldValidation={customValidation}
+/>
+```
+
+## Related Components
+
+- **[CountrySelect](./components-ui-form-elements-country-select.md)**: The `AddressForm` uses this component internally to provide a searchable, user-friendly country dropdown with flags.

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

@@ -0,0 +1,105 @@
+# 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.
+
+## 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. |
+
+## 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.
+
+```jsx
+import { useState } from 'react';
+import { FormProvider, useForm } from 'react-hook-form';
+import { CountrySelect } from '@blocklet/payment-react';
+import { Box } from '@mui/material';
+import type { CountryIso2 } from 'react-international-phone';
+
+function BasicCountrySelect() {
+  const [selectedCountry, setSelectedCountry] = useState<CountryIso2>('us');
+  const methods = useForm({
+    defaultValues: {
+      country: 'us',
+    },
+  });
+
+  const handleCountryChange = (country: CountryIso2) => {
+    setSelectedCountry(country);
+    console.log('Selected Country:', country);
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <Box sx={{ maxWidth: 300 }}>
+        <CountrySelect
+          name="country"
+          value={selectedCountry}
+          onChange={handleCountryChange}
+        />
+      </Box>
+    </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.
+
+### 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.
+
+### 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.
+
+## Customization
+
+### Displaying the Dial Code
+
+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.
+
+```jsx
+import { useState } from 'react';
+import { FormProvider, useForm } from 'react-hook-form';
+import { CountrySelect } from '@blocklet/payment-react';
+import { Box } from '@mui/material';
+import type { CountryIso2 } from 'react-international-phone';
+
+function CountrySelectWithDialCode() {
+  const [country, setCountry] = useState<CountryIso2>('us');
+  const methods = useForm({ defaultValues: { country: 'us' } });
+
+  return (
+    <FormProvider {...methods}>
+      <Box sx={{ maxWidth: 300 }}>
+        <CountrySelect
+          name="country"
+          value={country}
+          onChange={setCountry}
+          showDialCode={true}
+        />
+      </Box>
+    </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.