@blocklet/payment-react 1.19.22 → 1.20.0

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

@@ -0,0 +1,124 @@
+# 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.
+
+## 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")
+  };
+}
+```
+
+## Example Usage
+
+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. 
+
+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).
+
+```tsx
+import React, { useState } from 'react';
+import { CurrencySelector, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session'; // Assuming a local session context hook
+import type { TPaymentCurrency } from '@blocklet/payment-types';
+import { Box, Typography, CircularProgress } from '@mui/material';
+
+// Mock data representing available currencies
+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',
+    method: {
+      id: 'bitcoin_network',
+      name: 'Bitcoin Network',
+    },
+  },
+  {
+    id: 'eth_native',
+    logo: 'https://cdn.jsdelivr.net/gh/atomiclabs/cryptocurrency-icons@1a63530be6e374711a8554f31b17e4cb92c25661/svg/color/eth.svg',
+    name: 'Ethereum',
+    symbol: 'ETH',
+    method: {
+      id: 'ethereum_network',
+      name: 'Ethereum Network',
+    },
+  },
+];
+
+function CurrencySelectorExample() {
+  const [selectedCurrencyId, setSelectedCurrencyId] = useState<string>('usdt_tron');
+
+  const handleCurrencyChange = (currencyId: string, methodId?: string) => {
+    console.log(`Selected Currency ID: ${currencyId}, Method ID: ${methodId}`);
+    setSelectedCurrencyId(currencyId);
+  };
+
+  return (
+    <Box sx={{ padding: 2, border: '1px solid #ddd', borderRadius: '4px' }}>
+      <Typography variant="h6" gutterBottom>
+        Select Your Payment Currency
+      </Typography>
+      <CurrencySelector
+        value={selectedCurrencyId}
+        currencies={mockCurrencies}
+        onChange={handleCurrencyChange}
+      />
+      <Typography sx={{ marginTop: '20px' }}>
+        Current Selection: <strong>{selectedCurrencyId}</strong>
+      </Typography>
+    </Box>
+  );
+}
+
+// Most components from this library must be wrapped in PaymentProvider.
+export default function MyPaymentPage() {
+  const { session, connectApi } = useSessionContext();
+
+  // PaymentProvider requires session and connectApi.
+  // Ensure these are available before rendering.
+  if (!session || !connectApi) {
+    return <CircularProgress />;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <CurrencySelectorExample />
+    </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.

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

@@ -0,0 +1,160 @@
+# 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.
+
+### Features
+
+- **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.
+
+## Props
+
+The `PhoneInput` component accepts all standard props from Material-UI's `TextField` in addition to its own 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`. | - |
+
+## 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
+
+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.
+
+```tsx
+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';
+
+export default function PhoneForm() {
+  const methods = useForm({
+    mode: 'onBlur', // Validate on blur
+    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 })}
+          />
+          <PhoneInput
+            label="Phone Number"
+            name="phone"
+            required
+            {...register('phone', {
+              required: 'Phone number is required.',
+              validate: async (value) => {
+                const isValid = await validatePhoneNumber(value);
+                return isValid || 'Please enter a valid phone number';
+              },
+            })}
+            error={!!errors.phone}
+            helperText={errors.phone?.message?.toString()}
+          />
+          <Button type="submit" variant="contained">
+            Submit
+          </Button>
+        </Stack>
+      </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.
+
+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.
+
+The following diagram illustrates this interaction:
+
+```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'
+```
+
+This utility is particularly helpful for normalizing phone numbers before submitting them to a backend service.

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

@@ -0,0 +1,125 @@
+# 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.
+
+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.
+
+<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.
+  </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.
+  </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.
+  </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>
+</x-cards>
+
+## Usage Patterns
+
+Most form elements are designed to work within a `react-hook-form` context, while others can be used as standalone components.
+
+### Form-Based Components
+
+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
+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';
+
+function MyContactForm() {
+  const methods = useForm({
+    defaultValues: {
+      phone: '',
+      billing_address: {
+        line1: '',
+        city: '',
+        state: '',
+        postal_code: '',
+        country: 'us',
+      },
+    },
+  });
+
+  const validatePhoneNumber = async (phone) => {
+    const phoneUtil = await getPhoneUtil();
+    return phoneUtil.isValid(phone) || 'Invalid phone number';
+  };
+
+  const onSubmit = (data) => {
+    console.log('Form data:', 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>
+      </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}
+    />
+  );
+}
+```
+
+## 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.

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

@@ -0,0 +1,157 @@
+# 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.
+
+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.
+
+## 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`. |
+
+## 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.
+
+For details on setting up the provider, please see the [PaymentProvider documentation](./providers-payment-provider.md).
+
+### 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.
+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...
+  },
+];
+
+const currency = {
+  id: 'usd',
+  symbol: '$',
+  decimal: 2,
+  // other TPaymentCurrency properties...
+};
+
+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 = [
+  {
+    price_id: 'price_456',
+    quantity: 1,
+    price: {
+      product: { name: 'Pro Plan' },
+      type: 'recurring',
+      recurring: { interval: 'year', interval_count: 1, usage_type: 'licensed' },
+      unit_amount: '100.00',
+    },
+  },
+];
+const currency = { id: 'usd', symbol: '$', decimal: 2 };
+
+function StakingCheckoutPage() {
+  return (
+    <PaymentSummary
+      items={recurringItems}
+      currency={currency}
+      showStaking={true}
+      billingThreshold={50} // Optional: Sets a fixed staking amount
+    />
+  );
+}
+```
+
+### Handling Cross-Sells
+
+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.
+
+```jsx
+// Note: Ensure this component is rendered within a PaymentProvider.
+import React from 'react';
+import { PaymentSummary } from '@blocklet/payment-react';
+
+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
+  };
+
+  const handleCancelCrossSell = async () => {
+    console.log('Canceling cross-sell');
+    // Add logic to update the checkout session via API call
+  };
+
+  return (
+    <PaymentSummary
+      items={items}
+      currency={currency}
+      checkoutSessionId="cs_12345"
+      crossSellBehavior="required"
+      onApplyCrossSell={handleApplyCrossSell}
+      onCancelCrossSell={handleCancelCrossSell}
+    />
+  );
+}
+```
+
+### 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.