@blocklet/payment-react 1.20.5 → 1.20.6

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

@@ -1,125 +1,91 @@
 # Form Elements
 
-The `@blocklet/payment-react` library provides a collection of granular input components for building custom payment and contact information forms. These components come with built-in validation, internationalization support, and a responsive UI, simplifying the process of collecting user data.
+The `@blocklet/payment-react` library provides a collection of granular input components designed to simplify the creation of custom payment and contact information forms. These elements are built with validation and user experience in mind, integrating smoothly with `react-hook-form` to provide a robust and flexible solution for data collection.
 
-This section provides an overview of the key form elements. For detailed props and advanced usage, please refer to the specific documentation for each component linked below.
+Each component is designed to be a self-contained unit, allowing you to compose them into complex forms tailored to your specific requirements. Below is an overview of the available form elements.
 
 <x-cards data-columns="2">
   <x-card data-title="AddressForm" data-icon="lucide:map-pin" data-href="/components/ui/form-elements/address-form">
-    A pre-built form for collecting billing address details, with validation that adapts to the selected country.
+    A pre-built form for collecting billing address details with country-specific validation.
   </x-card>
   <x-card data-title="PhoneInput" data-icon="lucide:phone" data-href="/components/ui/form-elements/phone-input">
-    An international phone number input with an integrated country selector, dial code display, and validation.
+    An international phone number input with an integrated country code selector and validation.
   </x-card>
   <x-card data-title="CountrySelect" data-icon="lucide:globe" data-href="/components/ui/form-elements/country-select">
-    A searchable dropdown for selecting a country, complete with flags and a responsive design for mobile and desktop.
+    A searchable dropdown for selecting a country, complete with flags and a mobile-friendly UI.
   </x-card>
-  <x-card data-title="CurrencySelector" data-icon="lucide:circle-dollar-sign" data-href="/components/ui/form-elements/currency-selector">
-    A component that allows users to select their preferred payment currency from a list of available options.
+  <x-card data-title="CurrencySelector" data-icon="lucide:coins" data-href="/components/ui/form-elements/currency-selector">
+    A component that allows users to choose their preferred payment currency from available options.
   </x-card>
 </x-cards>
 
-## Usage Patterns
+## Common Usage Pattern
 
-Most form elements are designed to work within a `react-hook-form` context, while others can be used as standalone components.
+These form elements are intended to be used within a `FormProvider` from `react-hook-form`. You can compose them to build comprehensive forms that capture all the necessary information for a transaction. While each component has its own set of properties, they share a common integration pattern.
 
-### Form-Based Components
+Here is a basic example of how you might combine several form elements to create a user information form:
 
-Components like `AddressForm` and `PhoneInput` should be wrapped in a `FormProvider` from `react-hook-form`. This allows them to share form state, validation, and submission logic seamlessly.
-
-Here is an example of how to combine them into a single form:
-
-```jsx
+```jsx MyCustomForm.tsx icon=logos:react
 import { FormProvider, useForm } from 'react-hook-form';
-import { AddressForm, PhoneInput } from '@blocklet/payment-react';
-import { Button } from '@mui/material';
-import { getPhoneUtil } from '@blocklet/payment-react/libs/phone-validator';
+import { AddressForm, PhoneInput, CurrencySelector } from '@blocklet/payment-react';
+import { Button, Stack } from '@mui/material';
+
+// Assume `availableCurrencies` is fetched from your backend
+const availableCurrencies = [
+  {
+    id: 'usd_xxx',
+    name: 'USD',
+    symbol: 'USD',
+    logo: 'url/to/usd_logo.png',
+    method: { id: 'stripe', name: 'Stripe' },
+  },
+  // ... other currencies
+];
 
-function MyContactForm() {
+function MyCustomForm() {
   const methods = useForm({
     defaultValues: {
-      phone: '',
+      currency: 'usd_xxx',
+      phone_number: '',
       billing_address: {
         line1: '',
         city: '',
         state: '',
         postal_code: '',
-        country: 'us',
+        country: 'US', // Use ISO2 code
       },
     },
   });
 
-  const validatePhoneNumber = async (phone) => {
-    const phoneUtil = await getPhoneUtil();
-    return phoneUtil.isValid(phone) || 'Invalid phone number';
-  };
-
   const onSubmit = (data) => {
-    console.log('Form data:', data);
+    console.log('Form data submitted:', data);
   };
 
   return (
     <FormProvider {...methods}>
       <form onSubmit={methods.handleSubmit(onSubmit)}>
-        <AddressForm mode="required" stripe={false} />
-        <PhoneInput
-          name="phone"
-          label="Phone Number"
-          rules={{ validate: validatePhoneNumber }}
-        />
-        <Button type="submit" variant="contained" sx={{ mt: 2 }}>
-          Submit
-        </Button>
+        <Stack spacing={2}>
+          <CurrencySelector
+            value={methods.watch('currency')}
+            currencies={availableCurrencies}
+            onChange={(currencyId) => methods.setValue('currency', currencyId)}
+          />
+          <PhoneInput name="phone_number" label="Phone Number" required />
+          <AddressForm mode="required" stripe={false} />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+        </Stack>
       </form>
     </FormProvider>
   );
 }
 ```
 
-### Standalone Components
-
-Components like `CurrencySelector` are self-contained and manage their state via props and callbacks, so they don't need to be inside a `FormProvider`.
-
-```jsx
-import { CurrencySelector } from '@blocklet/payment-react';
-import { useState } from 'react';
-
-// Example currency data structure
-const sampleCurrencies = [
-  {
-    id: 'usd_credit_card',
-    name: 'USD',
-    symbol: '$',
-    logo: 'https://example.com/usd-logo.png',
-    method: { id: 'card', name: 'Credit Card' },
-  },
-  {
-    id: 'eth_mainnet',
-    name: 'Ethereum',
-    symbol: 'ETH',
-    logo: 'https://example.com/eth-logo.png',
-    method: { id: 'crypto', name: 'Ethereum Network' },
-  },
-];
-
-function MyCurrencyComponent() {
-  const [selectedCurrency, setSelectedCurrency] = useState('usd_credit_card');
-
-  const handleChange = (currencyId, methodId) => {
-    setSelectedCurrency(currencyId);
-    console.log('Selected payment method:', methodId);
-  };
-
-  return (
-    <CurrencySelector
-      currencies={sampleCurrencies}
-      value={selectedCurrency}
-      onChange={handleChange}
-    />
-  );
-}
-```
+In this example, `CurrencySelector`, `PhoneInput`, and `AddressForm` are combined within a single form. `CurrencySelector` is used as a controlled component tied to the form's state, while `PhoneInput` and `AddressForm` are uncontrolled components that automatically register their fields and validation rules with the `react-hook-form` context.
 
 ## Next Steps
 
-Now that you have an overview of the individual form elements, you can explore their detailed documentation for advanced configurations. For building a complete payment experience, consider using higher-level components like [`CheckoutForm`](./components-checkout-checkout-form.md), which integrate these elements into a complete and managed flow.
+To learn more about the specific properties and implementation details of each component, please explore their individual documentation pages. 
+
+Start with the [AddressForm](./components-ui-form-elements-address-form.md) to see how to collect billing information.

package/docs/components-ui-payment-summary.md

@@ -1,157 +1,109 @@
 # PaymentSummary
 
-The `PaymentSummary` component displays a detailed overview of an order within the checkout flow. It lists all line items, shows any applicable trial periods or staking requirements, and calculates the total amount due. It is designed to give customers a clear and transparent breakdown of their purchase before they complete the payment.
+The `PaymentSummary` component is a crucial UI element for any checkout process. It provides a detailed breakdown of the order, including all line items, trial period information, staking requirements, and the final total amount. It's designed to be responsive and adapts its layout for mobile devices.
 
-This component works in conjunction with `ProductItem` to render individual items and can adapt its display for various scenarios, including cross-sells, upsells, and donations.
+This component works in tandem with `ProductItem` and `ProductDonation` to render each item in the cart, and it handles user interactions like applying cross-sells or changing quantities.
 
 ## Props
 
-The `PaymentSummary` component accepts the following props to customize its behavior and the information it displays.
-
-| Prop | Type | Description |
-|---|---|---|
-| `items` | `TLineItemExpanded[]` | **Required.** An array of line item objects to be displayed in the summary. |
-| `currency` | `TPaymentCurrency` | **Required.** The currency object used for formatting amounts. |
-| `trialInDays` | `number` | The number of days for a trial period. Defaults to `0`. |
-| `trialEnd` | `number` | A Unix timestamp indicating when the trial ends. |
-| `billingThreshold` | `number` | The billing threshold for staking calculations. |
-| `showStaking` | `boolean` | If `true`, staking information will be calculated and displayed. Defaults to `false`. |
-| `onUpsell` | `(from: string, to: string) => void` | Callback function triggered when a user accepts an upsell offer. |
-| `onDownsell` | `(from: string) => void` | Callback function triggered when a user reverts an upsell offer. |
-| `onQuantityChange` | `(itemId: string, quantity: number) => void` | Callback function for when the quantity of an item is changed. |
-| `onChangeAmount` | `(amount: number) => void` | Callback function for when a custom donation amount is changed. |
-| `onApplyCrossSell` | `(crossSellId: string) => void` | Callback function to add a cross-sell item to the cart. |
-| `onCancelCrossSell` | `() => void` | Callback function to remove a cross-sell item from the cart. |
-| `checkoutSessionId` | `string` | The ID of the current checkout session, used to fetch available cross-sell offers. |
-| `crossSellBehavior` | `'required' \| 'optional'` | Defines the behavior of the cross-sell offer. Defaults to `''` (optional). |
-| `donationSettings` | `DonationSettings` | Configuration object for donation items. |
-| `action` | `string` | A custom title to display at the top of the summary box (e.g., "Renew Subscription"). Defaults to "Order Summary". |
-| `completed` | `boolean` | If `true`, disables interactive elements like quantity adjustments, as the checkout is complete. Defaults to `false`. |
+The `PaymentSummary` component accepts the following props to customize its behavior and display:
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `items` | `TLineItemExpanded[]` | Yes | An array of line items to be displayed in the summary. |
+| `currency` | `TPaymentCurrency` | Yes | The currency object for formatting amounts. |
+| `trialInDays` | `number` | Yes | The number of trial days for recurring subscriptions. |
+| `billingThreshold` | `number` | Yes | The billing threshold amount. Used in staking calculation if applicable. |
+| `trialEnd` | `number` | No | A Unix timestamp for when the trial ends. Overrides `trialInDays`. |
+| `showStaking` | `boolean` | No | If `true`, displays staking details. Defaults to `false`. |
+| `onUpsell` | `(from: string, to: string) => void` | No | Callback function when a user accepts an upsell offer. |
+| `onDownsell` | `(from: string) => void` | No | Callback function when a user reverts an upsell offer. |
+| `onQuantityChange` | `(itemId: string, quantity: number) => void` | No | Callback function when the quantity of an item is changed. |
+| `onChangeAmount` | `(itemId: string, amount: string) => void` | No | Callback for changing the amount of a custom-amount item, like a donation. |
+| `onApplyCrossSell` | `(crossSellId: string) => void` | No | Callback function when a user adds a cross-sell item. |
+| `onCancelCrossSell` | `() => void` | No | Callback function when a user removes a cross-sell item. |
+| `checkoutSessionId` | `string` | No | The ID of the checkout session, used to fetch potential cross-sell items. |
+| `crossSellBehavior` | `string` | No | Defines the behavior of the cross-sell item (e.g., `'required'`). |
+| `donationSettings` | `DonationSettings` | No | Configuration for donation items. |
+| `action` | `string` | No | A custom title for the summary section, replacing "Order Summary". |
+| `completed` | `boolean` | No | If `true`, disables interactive elements like quantity adjustment. Defaults to `false`. |
 
 ## Usage
 
-The `PaymentSummary` component is typically placed within a checkout page to provide a persistent view of the order details. It must be wrapped by a `PaymentProvider` to access necessary context.
+The `PaymentSummary` component should be placed within a `PaymentProvider` and is typically used as part of a larger checkout form. You need to provide it with the line items and currency information.
 
-For details on setting up the provider, please see the [PaymentProvider documentation](./providers-payment-provider.md).
+Here is a basic example of how to integrate the `PaymentSummary` component.
 
-### Basic Order Summary
-
-Here is a basic example of rendering a payment summary. The component automatically calculates totals and displays item details based on the `items` and `currency` props.
-
-```jsx
-// Note: Ensure this component is rendered within a PaymentProvider.
+```tsx PaymentSummary Example icon=lucide:shopping-cart
 import React from 'react';
-import { PaymentSummary } from '@blocklet/payment-react';
-
-const items = [
-  {
-    price_id: 'price_123',
-    quantity: 2,
-    price: {
-      product: { name: 'Standard Plan', images: ['/logo.png'] },
-      type: 'recurring',
-      recurring: { interval: 'month', interval_count: 1 },
-      unit_amount: '10.00',
-    },
-    // other TLineItemExpanded properties...
-  },
-];
+import { PaymentProvider, PaymentSummary } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // Your session context hook
 
-const currency = {
-  id: 'usd',
+// Mock data for demonstration purposes
+const mockCurrency = {
+  id: 'usd_4573516104843264',
   symbol: '$',
+  name: 'USD',
   decimal: 2,
-  // other TPaymentCurrency properties...
+  isDefault: true,
 };
 
-function MyCheckoutPage() {
-  return (
-    <PaymentSummary
-      items={items}
-      currency={currency}
-      trialInDays={14}
-    />
-  );
-}
-```
-
-### Displaying Staking and Totals
-
-When `showStaking` is set to `true`, the component calculates and displays the required staking amount separately from the payment amount. The final total combines both values.
-
-```jsx
-// Note: Ensure this component is rendered within a PaymentProvider.
-import React from 'react';
-import { PaymentSummary } from '@blocklet/payment-react';
-
-const recurringItems = [
+const mockItems = [
   {
-    price_id: 'price_456',
+    id: 'li_1',
+    price_id: 'price_1',
     quantity: 1,
+    adjustable_quantity: { enabled: true, minimum: 1, maximum: 10 },
     price: {
-      product: { name: 'Pro Plan' },
+      id: 'price_1',
       type: 'recurring',
-      recurring: { interval: 'year', interval_count: 1, usage_type: 'licensed' },
-      unit_amount: '100.00',
+      recurring: { interval: 'month', interval_count: 1, usage_type: 'licensed' },
+      unit_amount: '2000',
+      product: {
+        name: 'Pro Plan',
+        images: [],
+      },
     },
   },
 ];
-const currency = { id: 'usd', symbol: '$', decimal: 2 };
 
-function StakingCheckoutPage() {
+export default function MyCheckoutPage() {
+  const { session, connectApi } = useSessionContext();
+
+  const handleQuantityChange = (itemId, newQuantity) => {
+    console.log(`Item ${itemId} quantity changed to ${newQuantity}`);
+    // Here you would typically update your state and refetch checkout info
+  };
+
   return (
-    <PaymentSummary
-      items={recurringItems}
-      currency={currency}
-      showStaking={true}
-      billingThreshold={50} // Optional: Sets a fixed staking amount
-    />
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <PaymentSummary
+        items={mockItems}
+        currency={mockCurrency}
+        trialInDays={14}
+        billingThreshold={0}
+        showStaking={true}
+        onQuantityChange={handleQuantityChange}
+      />
+    </PaymentProvider>
   );
 }
 ```
 
-### Handling Cross-Sells
+### Displaying Staking and Totals
 
-By providing a `checkoutSessionId`, the component can fetch and display cross-sell offers. The `crossSellBehavior` prop determines if the offer is optional or required. User interactions are handled via the `onApplyCrossSell` and `onCancelCrossSell` callbacks.
+If `showStaking` is set to `true`, the component will calculate and display the required staking amount for recurring items. It separates the amount due for immediate payment from the amount required for staking, providing a clear financial summary to the user. The final total combines these amounts.
 
-```jsx
-// Note: Ensure this component is rendered within a PaymentProvider.
-import React from 'react';
-import { PaymentSummary } from '@blocklet/payment-react';
+### Handling Trial Periods
 
-const items = [
-  {
-    price_id: 'price_123',
-    quantity: 1,
-    price: { product: { name: 'Main Product' }, unit_amount: '25.00' },
-  },
-];
-const currency = { id: 'usd', symbol: '$', decimal: 2 };
-
-function CrossSellCheckoutPage() {
-  const handleApplyCrossSell = async (crossSellId) => {
-    console.log('Applying cross-sell:', crossSellId);
-    // Add logic to update the checkout session via API call
-  };
+The component clearly communicates trial periods to the user. By passing `trialInDays` or `trialEnd`, a message like "Then $20.00 / month" will be displayed below the total, informing the user about the recurring charges after the trial concludes.
 
-  const handleCancelCrossSell = async () => {
-    console.log('Canceling cross-sell');
-    // Add logic to update the checkout session via API call
-  };
+### Interactive Features
 
-  return (
-    <PaymentSummary
-      items={items}
-      currency={currency}
-      checkoutSessionId="cs_12345"
-      crossSellBehavior="required"
-      onApplyCrossSell={handleApplyCrossSell}
-      onCancelCrossSell={handleCancelCrossSell}
-    />
-  );
-}
-```
+- **Quantity Adjustment**: If an item has `adjustable_quantity.enabled` set to `true`, the `PaymentSummary` (via its child `ProductItem`) will render controls to increase or decrease the quantity. The `onQuantityChange` callback is triggered upon modification.
+- **Upsell/Downsell**: For products with an upsell configuration, a switch is rendered to allow users to upgrade their plan. The `onUpsell` and `onDownsell` callbacks handle these actions.
+- **Cross-Sell**: If a `checkoutSessionId` is provided, the component can fetch and display suggested cross-sell items. Buttons to add or remove these items trigger the `onApplyCrossSell` and `onCancelCrossSell` callbacks.
 
 ### Mobile Responsiveness
 
-On mobile devices, the component automatically renders a collapsible section for the product list to save screen space. The list is initially collapsed if it contains three or more items. This behavior is handled internally using the `useMobile` hook and requires no extra configuration.
+On mobile devices, the list of products is collapsible by default to save space, especially for orders with many items. Users can tap to expand or collapse the list, providing a cleaner and more user-friendly experience on smaller screens.