@blocklet/payment-react 1.20.5 → 1.20.7

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

@@ -1,104 +1,110 @@
 # 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).
+The `CustomerInvoiceList` component is designed to render a customer's invoice history. It fetches and displays invoice data from the payment service, offering two distinct layouts: a simple, date-grouped list with infinite scroll, and a detailed, paginated table. This component must be used within a `PaymentProvider` to function correctly.
 
 ## 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. | `''` |
+| `subscription_id` | `string` | Filter invoices by a specific subscription ID. | `''` |
+| `currency_id` | `string` | Filter 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
+| `include_return_staking` | `boolean` | If `true`, includes return staking invoices. | `false` |
+| `include_recovered_from` | `boolean` | If `true`, includes invoices that were recovered from a previous balance. | `false` |
+| `status` | `string` | A comma-separated string of invoice statuses to display (e.g., `'open,paid,uncollectible'`). | `'open,paid,uncollectible'` |
+| `pageSize` | `number` | The number of invoices to fetch per page. | `10` |
+| `target` | `string` | The target attribute for invoice links (e.g., `'_self'`, `'_blank'`). | `'_self'` |
+| `action` | `string` | Defines a call-to-action for certain invoices. Set to `'pay'` to show a pay button for open invoices. | `''` |
+| `type` | `'list' \| 'table'` | The display mode for the invoice list. | `'list'` |
+| `onTableDataChange` | `Function` | A callback function that is triggered when the invoice data changes. | `() => {}` |
+| `relatedSubscription` | `boolean` | In `table` mode, if `true`, shows a column with a link to the related subscription. | `false` |
 
-### Basic Invoice History
+## Basic Usage (List View)
 
-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.
+The default view (`type="list"`) renders a simple list of invoices, grouped by date, with an infinite scroll mechanism to load more items.
 
-```tsx
+```tsx CustomerInvoiceListPage.tsx icon=logos:react
 import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
-import { useSessionContext } from '../hooks/session'; // Your local session context hook
 
-function InvoiceHistoryPage({ subscriptionId }) {
-  const { session, connectApi } = useSessionContext();
+function InvoiceHistoryPage() {
+  // Assuming customerId is available, e.g., from session or props
+  const customerId = 'cus_xxxxxxxxxxxxxx';
 
   return (
-    <PaymentProvider session={session} connect={connectApi}>
-      <h2>Invoice History</h2>
-      <CustomerInvoiceList
-        subscription_id={subscriptionId}
-        status="paid,void"
-      />
+    <PaymentProvider>
+      <CustomerInvoiceList customer_id={customerId} />
     </PaymentProvider>
   );
 }
 ```
 
-### Detailed Invoice Table
+## Table View
 
-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.
+For a more detailed and structured presentation, you can set `type="table"`. This mode displays invoices in a paginated table with sortable columns.
 
-```tsx
+```tsx CustomerInvoiceTablePage.tsx icon=logos:react
 import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
-import { useSessionContext } from '../hooks/session'; // Your local session context hook
 
-function CustomerDashboard({ customerId }) {
-  const { session, connectApi } = useSessionContext();
+function InvoiceHistoryTable() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
 
   return (
-    <PaymentProvider session={session} connect={connectApi}>
-      <h3>All Invoices</h3>
+    <PaymentProvider>
       <CustomerInvoiceList
         customer_id={customerId}
         type="table"
-        pageSize={20}
-        include_staking={true}
-        relatedSubscription={true}
-        status="open,paid,uncollectible,void"
+        relatedSubscription={true} // Show a column for the related subscription
+        pageSize={5}
       />
     </PaymentProvider>
   );
 }
 ```
 
-### Invoices with Payment Action
+In this example, the `relatedSubscription` prop is enabled to add a column that links directly to the subscription associated with each invoice, which is useful for subscription-based services.
 
-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.
+## Filtering Invoices
 
-```tsx
+You can use various props to filter the invoices displayed. For example, to show only paid invoices related to staking:
+
+```tsx FilteredInvoiceListPage.tsx icon=logos:react
 import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
-import { useSessionContext } from '../hooks/session'; // Your local session context hook
 
-function PayInvoices({ customerId }) {
-  const { session, connectApi } = useSessionContext();
+function FilteredInvoiceList() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
 
   return (
-    <PaymentProvider session={session} connect={connectApi}>
-      <h3>Outstanding Invoices</h3>
+    <PaymentProvider>
       <CustomerInvoiceList
         customer_id={customerId}
-        status="open,uncollectible"
-        action="pay" // This enables the "Pay" button
         type="table"
+        status="paid" // Only show paid invoices
+        include_staking={true} // Also include staking transactions
       />
     </PaymentProvider>
   );
 }
 ```
 
-### Real-time Updates
+## Enabling Payments for Open Invoices
+
+By setting the `action` prop to `'pay'`, you can add a "Pay" button to any invoices with `open` or `uncollectible` status. Clicking this button will initiate the payment flow using the `connect` instance from `PaymentProvider`.
+
+```tsx PayableInvoiceListPage.tsx icon=logos:react
+import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
+
+function PayableInvoiceList() {
+  const customerId = 'cus_xxxxxxxxxxxxxx';
 
-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.
+  return (
+    <PaymentProvider>
+      <CustomerInvoiceList
+        customer_id={customerId}
+        status="open,uncollectible" // Show only invoices that need payment
+        action="pay" // Add a "Pay" button
+      />
+    </PaymentProvider>
+  );
+}
+```

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

@@ -1,65 +1,44 @@
 # 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.
+The `CustomerPaymentList` component renders a detailed history of a customer's payments. It automatically handles fetching, pagination via infinite scroll, and grouping of payments by date, providing a clear and organized view of a user's transaction history.
+
+This component is ideal for user dashboards or account pages where customers need to review their past transactions.
 
 ## Props
 
-| Prop | Type | Description | Required |
+| Prop | Type | Required | Description |
 |---|---|---|---|
-| `customer_id` | `string` | The ID of the customer whose payment history should be displayed. | Yes |
+| `customer_id` | `string` | Yes | The unique identifier for the customer (e.g., the user's DID) whose payment history you want to display. |
 
 ## 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.
+To use the `CustomerPaymentList`, you must wrap it in a `PaymentProvider` and provide the required `customer_id`.
 
-```tsx
+```tsx Customer Payment History icon=logos:react
 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';
+import { useSessionContext } from './hooks/useSessionContext'; // Adjust path to your session context hook
 
-function CustomerProfilePage() {
-  // Get session and connectApi from your application's session context.
+export default function CustomerDashboard() {
   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>;
+  // Ensure the user is logged in to get their DID
+  if (!session?.user?.did) {
+    return <div>Please log in to view your payment history.</div>;
   }
 
   return (
     <PaymentProvider session={session} connect={connectApi}>
-      <Box sx={{ p: 3 }}>
-        <Typography variant="h5" gutterBottom>
-          Payment History
-        </Typography>
-        <CustomerPaymentList customer_id={customerDid} />
-      </Box>
+      <h2>My Payment History</h2>
+      <CustomerPaymentList customer_id={session.user.did} />
     </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.
+- **Automatic Data Fetching**: The component fetches payment intents from the API endpoint `/api/payment-intents`.
+- **Infinite Scroll**: It automatically loads more payments as the user requests them, ensuring efficient data handling for long payment histories.
+- **Date Grouping**: Payments are visually grouped by date, making the list easy to scan.
+- **Detailed Information**: For each payment, it displays the creation time, amount, status, description, and a link to the blockchain transaction if available.
+- **Loading and Empty States**: It includes a loading indicator during data fetching and displays a user-friendly message if the customer has no payment history.

package/docs/components-history.md

@@ -1,92 +1,67 @@
 # 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.
+The `@blocklet/payment-react` library provides a suite of history components designed to give your users a clear and detailed view of their past activities. These components are essential for building customer portals, account dashboards, and administrative interfaces where users need to track their billing, payments, and credit usage.
 
-```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.
+These components fetch and display data directly from the payment service, offering a seamless way to present historical information without needing to build complex data-fetching and rendering logic from scratch.
 
 <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 data-title="CustomerInvoiceList" data-icon="lucide:receipt-text" data-href="/components/history/invoice-list">
+    Render a list or table of a customer's invoices, including details on status, amount, and creation date.
   </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.
+    Display a customer's complete payment history, including transaction details, payment method, and status.
   </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 data-title="CreditGrantsList" data-icon="lucide:award" data-href="/components/history/credit-grants-list">
+    Show a list of all credit grants for a customer, detailing the status, remaining amount, and effective dates.
   </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 data-title="CreditTransactionsList" data-icon="lucide:history" data-href="/components/history/credit-transactions-list">
+    List all individual credit transactions, providing a detailed log of credit usage and adjustments over time.
   </x-card>
 </x-cards>
 
-### Example: Building a Billing Page
+## Common Use Case
 
-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.
+A typical use case is to create a "Billing History" section in a user's account page. You can use a tabbed interface to switch between different history views, such as Invoices, Payments, and Credits.
 
-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).
+Below is a conceptual example of how you might structure such a page.
 
-```jsx
+```jsx MyBillingPage.tsx icon=lucide:user
 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);
-  };
+import { CustomerInvoiceList, CustomerPaymentList } from '@blocklet/payment-react';
 
-  // The customerId is the user's DID from the session.
-  const customerId = session.user?.did;
+// Assume you have the customer's ID from your session or context
+const customerId = 'cus_xxxxxxxxxxxxxx';
 
-  if (!session.ready || !customerId) {
-    return <Typography>Please log in to view your billing history.</Typography>;
-  }
+export default function MyBillingPage() {
+  // In a real application, you would use state to manage the active tab
+  const [activeTab, setActiveTab] = React.useState('invoices');
 
   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>
+    <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>
   );
 }
 ```
 
-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.
+This example demonstrates how you can easily embed the history components to provide comprehensive, self-service billing information to your users. Each component handles its own data fetching, pagination, and display logic.
 
-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).
+Explore the detailed documentation for each component to understand its specific props and customization options.

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

@@ -1,66 +1,56 @@
 # 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.
+The `AddressForm` component provides a pre-built UI for collecting billing address information. It integrates seamlessly with `react-hook-form` and includes built-in, country-specific validation for fields like postal codes.
 
-This component is designed to work seamlessly within the context of `react-hook-form`.
+This component is designed to be flexible, supporting both full address collection and a simplified version for Stripe postal code verification.
 
 ## 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 |
+| Prop              | Type                               | Description                                                                                                                              | Default         |
+| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `mode`            | `string`                           | Determines the fields to display. Set to `'required'` to show the complete address form (line 1, city, state, postal code, country).       | `undefined`     |
+| `stripe`          | `boolean`                          | If `true`, displays a simplified form with only the postal code and country, typically used for card validation with Stripe.             | `false`         |
+| `sx`              | `SxProps`                          | MUI's `sx` prop for custom styling of the root `Stack` component.                                                                        | `{}`            |
+| `fieldValidation` | `Record<string, any>`              | An object for providing custom validation rules, such as regex patterns, for specific fields. See the validation section for details. | `{}`            |
+| `errorPosition`   | `'right'` \| `'bottom'`             | Specifies where to display validation error messages relative to the input field.                                                      | `'right'`       |
 
-## Integration with React Hook Form
+## Usage
 
-`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. 
+`AddressForm` must be used within a `FormProvider` from `react-hook-form` because it relies on its context to register fields and manage state.
 
-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).
+### Standard Billing Address
 
-## Usage Scenarios
+To collect a full billing address, set the `mode` prop to `'required'`. This will render all standard address fields, each with a 'required' validation rule.
 
-### Complete Address Form
-
-To collect a full billing address, set the `mode` prop to `'required'`. This will render all address fields as mandatory.
-
-```jsx
+```tsx AddressForm with Full Address icon=material-symbols:location-on-outline
 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();
+import AddressForm from './AddressForm'; // Adjust the import path
 
+export default function FullAddressExample() {
   const methods = useForm({
-    mode: 'onTouched',
     defaultValues: {
       billing_address: {
         line1: '',
         city: '',
         state: '',
         postal_code: '',
-        country: 'US',
+        country: 'US', // Default country
       },
     },
   });
 
   const onSubmit = (data) => {
-    alert('Form Submitted! Check console for data.');
-    console.log('Billing Address:', data.billing_address);
+    console.log('Form data:', data);
   };
 
   return (
     <FormProvider {...methods}>
       <form onSubmit={methods.handleSubmit(onSubmit)}>
         <Stack spacing={2}>
-          <AddressForm mode="required" stripe={false} errorPosition="bottom" />
+          <AddressForm mode="required" />
           <Button type="submit" variant="contained">
-            Submit Address
+            Submit
           </Button>
         </Stack>
       </form>
@@ -69,40 +59,36 @@ export default function FullAddressFormExample() {
 }
 ```
 
-### Simplified Stripe Form
+This setup renders input fields for the address line, city, state, and postal code. The country is selected via the integrated [CountrySelect](./components-ui-form-elements-country-select.md) component.
+
+### Stripe Postal Code Verification
 
-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`.
+When using payment methods like Stripe, you often only need the postal code and country for card verification. Set the `stripe` prop to `true` to render a simplified form containing only these two fields.
 
-```jsx
+```tsx AddressForm for Stripe icon=logos:stripe
 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();
+import AddressForm from './AddressForm'; // Adjust the import path
 
+export default function StripeAddressExample() {
   const methods = useForm({
-    mode: 'onTouched',
     defaultValues: {
       billing_address: {
         postal_code: '',
-        country: 'US',
+        country: 'US', // Default country
       },
     },
   });
 
   const onSubmit = (data) => {
-    alert('Form Submitted! Check console for data.');
-    console.log('Billing Info:', data.billing_address);
+    console.log('Form data:', data);
   };
 
   return (
     <FormProvider {...methods}>
       <form onSubmit={methods.handleSubmit(onSubmit)}>
         <Stack spacing={2}>
-          <AddressForm mode="optional" stripe={true} errorPosition="bottom" />
+          <AddressForm stripe={true} />
           <Button type="submit" variant="contained">
             Submit
           </Button>
@@ -115,36 +101,22 @@ export default function StripeAddressFormExample() {
 
 ## Validation
 
-`AddressForm` handles validation for required fields automatically. It also includes special validation logic for postal codes.
+The component includes automatic validation for required fields. The most notable feature is the dynamic postal code validation, which adjusts its rules based on the selected country.
 
-### Postal Code Validation
+- **Required Fields**: All visible fields are automatically marked as required.
+- **Postal Code**: The validation logic uses the `validator/lib/isPostalCode` library. It checks the postal code format against the selected country's standard format (e.g., 5 digits for the US, alphanumeric for Canada). If a country's format is not explicitly supported, a general validation is applied.
+- **Custom Validation**: You can pass additional validation rules via the `fieldValidation` prop. For example, to enforce a specific pattern on the `state` field:
 
-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
+```tsx
 const customValidation = {
   'billing_address.state': {
     pattern: '^[A-Z]{2}$',
     pattern_message: {
-      en: 'State must be a 2-letter abbreviation.',
-      // Add other locales as needed
+      en: 'State must be a 2-letter code.',
     },
   },
 };
 
-<AddressForm
-  mode="required"
-  stripe={false}
-  fieldValidation={customValidation}
-/>
+<AddressForm mode="required" 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.