@blocklet/payment-react 1.20.5 → 1.20.7

package/docs/components-ui-pricing-table.md

@@ -1,227 +1,140 @@
 # PricingTable
 
-The `PricingTable` component is a flexible UI element designed to display subscription plans and pricing options in a structured, user-friendly table. It allows users to browse different plans, switch between billing cycles (e.g., monthly, yearly), select a currency, and proceed to checkout by selecting a plan.
+The `PricingTable` component is a flexible UI element designed to display subscription plans and pricing options in a structured, responsive table. It allows users to toggle between billing cycles (e.g., monthly, yearly), select their preferred currency, and choose a plan to proceed with.
 
-This component must be used within the context of a `PaymentProvider`, as it relies on the provider for payment settings and currency information. For detailed instructions on setting up the provider, refer to the [PaymentProvider documentation](./providers-payment-provider.md).
-
-For a more integrated solution that bundles the pricing table with the complete checkout flow, consider using the higher-level [`CheckoutTable`](./components-checkout-checkout-table.md) component.
-
-```d2
-direction: down
-
-"PaymentProvider": {
-  shape: class
-  "Provides Context (Settings, Currency, etc.)"
-}
-
-"Your Application": {
-  shape: class
-  "Provides `table` data"
-  "Implements `onSelect` handler"
-}
-
-"PricingTable": {
-  shape: package
-  "Renders UI"
-  " - Billing Cycle Toggles"
-  " - Currency Selector"
-  " - Plan Cards"
-}
-
-"User": {
-  shape: person
-}
-
-"PaymentProvider" -> "PricingTable": "Provides context"
-"Your Application" -> "PricingTable": "Passes props (`table`, `onSelect`)"
-"User" -> "PricingTable": "Interacts (selects plan)"
-"PricingTable" -> "Your Application": "Triggers `onSelect(priceId, currencyId)`"
-
-```
+This component is ideal for building custom checkout flows where you need granular control over the presentation of pricing plans. For a more integrated solution that handles the entire checkout process, consider using the higher-level [`CheckoutTable`](./components-checkout-checkout-table.md) component.
 
 ## Props
 
-The `PricingTable` component accepts the following props to customize its behavior and appearance:
-
-| Prop | Type | Required | Default | Description |
-|---|---|---|---|---|
-| `table` | `TPricingTableExpanded` | Yes | - | An object containing the pricing table data, including a list of items (plans) to display. |
-| `onSelect` | `(priceId: string, currencyId: string) => void` | Yes | - | A callback function that is invoked when a user clicks the action button for a plan. |
-| `alignItems` | `'center' \| 'left'` | No | `'center'` | Controls the horizontal alignment of the pricing plans and controls. |
-| `mode` | `'checkout' \| 'select'` | No | `'checkout'` | Determines the behavior and text of the action button. `'checkout'` is for direct payment, while `'select'` is for plan selection. |
-| `interval` | `string` | No | `''` | The initially selected billing interval (e.g., 'month-1', 'year-1'). If empty, the first available interval is used. |
-| `hideCurrency` | `boolean` | No | `false` | If `true`, the currency selection dropdown will be hidden from the user. |
-
-## Usage Scenarios
-
-### Basic Checkout Table
-
-This is the default mode. The component displays plans with a subscription button. When a user clicks the button, the `onSelect` callback is triggered, which you can use to initiate a checkout session.
-
-```jsx
-import React from 'react';
-import PricingTable from '@blocklet/payment-react/lib/components/pricing-table';
-import { PaymentProvider } from '@blocklet/payment-react/lib/contexts/payment';
-import { useSessionContext } from '../hooks/session'; // Your local session context hook
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `table` | `TPricingTableExpanded` | - | **Required**. An object containing the pricing table data, including a list of items (plans), currency information, and other details. |
+| `onSelect` | `(priceId: string, currencyId: string) => void` | - | **Required**. A callback function that is triggered when a user clicks the action button for a plan. It receives the selected `priceId` and `currencyId`. |
+| `alignItems` | `'center' \| 'left'` | `'center'` | Controls the horizontal alignment of the table's header content (billing cycle and currency selectors). |
+| `mode` | `'checkout' \| 'select'` | `'checkout'` | Determines the behavior and text of the action button. `'checkout'` mode is for initiating a payment, while `'select'` mode is for selecting a plan within a larger form. |
+| `interval` | `string` | `''` | Sets the initially selected billing interval. The format is typically `interval-interval_count` (e.g., `month-1`, `year-1`). |
+| `hideCurrency` | `boolean` | `false` | If `true`, the currency selector dropdown will be hidden, even if multiple currencies are available. |
+
+## Usage Example
+
+To use the `PricingTable`, you must wrap it in a `PaymentProvider`. The component requires a `table` object with your product data and an `onSelect` handler to manage user selections.
+
+```tsx Integration Example icon=lucide:code
+import { PaymentProvider } from '@blocklet/payment-react';
+import { PricingTable } from '@blocklet/payment-react/components/ui';
+import type { TPricingTableExpanded } from '@blocklet/payment-types';
+
+// In a real application, you would fetch this data from your payment service.
+const pricingTableData: TPricingTableExpanded = {
+  id: 'pt_123',
+  livemode: false,
+  currency: { id: 'usd', symbol: '$' },
+  items: [
+    {
+      price_id: 'price_basic_monthly',
+      product: {
+        name: 'Basic Plan',
+        description: 'For individuals and small teams.',
+        unit_label: 'user',
+        features: [{ name: '5 Projects' }, { name: '10GB Storage' }, { name: 'Basic Support' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '1000', // in cents
+        recurring: { interval: 'month', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '1000' }],
+      },
+      is_highlight: false,
+    },
+    {
+      price_id: 'price_pro_monthly',
+      product: {
+        name: 'Pro Plan',
+        description: 'For growing businesses.',
+        unit_label: 'user',
+        features: [{ name: 'Unlimited Projects' }, { name: '100GB Storage' }, { name: 'Priority Support' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '2500',
+        recurring: { interval: 'month', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '2500' }],
+      },
+      is_highlight: true,
+      highlight_text: 'Popular',
+    },
+    {
+      price_id: 'price_basic_yearly',
+      product: {
+        name: 'Basic Plan',
+        description: 'For individuals and small teams.',
+        unit_label: 'user',
+        features: [{ name: '5 Projects' }, { name: '10GB Storage' }, { name: 'Basic Support' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '10000',
+        recurring: { interval: 'year', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '10000' }],
+      },
+      is_highlight: false,
+    },
+    {
+      price_id: 'price_pro_yearly',
+      product: {
+        name: 'Pro Plan',
+        description: 'For growing businesses.',
+        unit_label: 'user',
+        features: [{ name: 'Unlimited Projects' }, { name: '100GB Storage' }, { name: 'Priority Support' }],
+      },
+      price: {
+        currency: 'usd',
+        unit_amount: '25000',
+        recurring: { interval: 'year', interval_count: 1 },
+        currency_options: [{ currency_id: 'usd', unit_amount: '25000' }],
+      },
+      is_highlight: true,
+      highlight_text: 'Popular',
+    },
+  ],
+};
 
-// Assume 'myPricingTableData' is fetched from your backend and conforms to TPricingTableExpanded
+function MyPricingPage() {
+  const { session, connect } = useSessionContext();
 
-function MyPricingPage({ myPricingTableData }) {
-  const handleSubscription = async (priceId, currencyId) => {
-    console.log(`Starting subscription for price: ${priceId} with currency: ${currencyId}`);
-    // Add your logic to create a checkout session and redirect the user
+  const handlePlanSelect = async (priceId: string, currencyId: string) => {
+    console.log(`Plan selected: ${priceId}, Currency: ${currencyId}`);
+    // Here, you would typically navigate to a checkout page or open a payment modal.
+    // For example: `router.push(\"/checkout?price_id=${priceId}&currency_id=${currencyId}\")`
+    alert(`Selected Price ID: ${priceId}`);
   };
 
   return (
-    <PricingTable 
-      table={myPricingTableData} 
-      onSelect={handleSubscription} 
-    />
-  );
-}
-
-// Your component must be wrapped in PaymentProvider
-function AppWithPayment() {
-  const { session, connectApi } = useSessionContext();
-
-  if (!session.user) {
-    return <button onClick={connectApi}>Connect Wallet</button>;
-  }
-
-  // Assume 'myPricingTableData' is available here
-  return (
-    <PaymentProvider session={session} connect={connectApi}>
-      <MyPricingPage myPricingTableData={myPricingTableData} />
+    <PaymentProvider session={session} connect={connect}>
+      <div style={{ maxWidth: 800, margin: 'auto' }}>
+        <PricingTable table={pricingTableData} onSelect={handlePlanSelect} />
+      </div>
     </PaymentProvider>
   );
 }
-```
-
-**Note:** The `useSessionContext` hook should be set up in your application to provide session information. For a detailed guide on how to configure this and the `PaymentProvider`, please see the [PaymentProvider documentation](./providers-payment-provider.md).
-
-### Plan Selection Mode
 
-By setting `mode='select'`, the component can be used as part of a larger form where the user selects a plan before proceeding. The action button text changes to "Select" or "Selected", and selected items are highlighted with a border.
-
-In this mode, you need to manage the selected plan in your parent component's state and pass the `is_selected` property down to the `table` items.
-
-```jsx
-import React, { useState, useMemo } from 'react';
-import PricingTable from '@blocklet/payment-react/lib/components/pricing-table';
-import { PaymentProvider } from '@blocklet/payment-react/lib/contexts/payment';
-import { useSessionContext } from '../hooks/session'; // Your local session context hook
-
-function PlanSelectionForm({ myPricingTableData }) {
-  const [selectedPriceId, setSelectedPriceId] = useState(null);
-
-  const handlePlanSelect = (priceId, currencyId) => {
-    setSelectedPriceId(priceId);
-    console.log(`User selected price: ${priceId} in currency: ${currencyId}`);
-  };
-
-  // Add is_selected property to the items based on the current state
-  const tableDataWithSelection = useMemo(() => ({
-    ...myPricingTableData,
-    items: myPricingTableData.items.map(item => ({
-      ...item,
-      is_selected: item.price_id === selectedPriceId,
-    })),
-  }), [myPricingTableData, selectedPriceId]);
-
-  return (
-    <div>
-      <h2>Choose Your Plan</h2>
-      <PricingTable 
-        table={tableDataWithSelection} 
-        onSelect={handlePlanSelect} 
-        mode="select"
-        alignItems="left"
-      />
-      <button disabled={!selectedPriceId}>Continue to Checkout</button>
-    </div>
-  );
-}
+export default MyPricingPage;
+```
 
-// Your component must be wrapped in PaymentProvider
-function AppWithPaymentSelection() {
-  const { session, connectApi } = useSessionContext();
+## Usage Scenarios
 
-  if (!session.user) {
-    return <button onClick={connectApi}>Connect Wallet</button>;
-  }
-  
-  // Assume 'myPricingTableData' is available here
-  return (
-    <PaymentProvider session={session} connect={connectApi}>
-      <PlanSelectionForm myPricingTableData={myPricingTableData} />
-    </PaymentProvider>
-  );
-}
-```
+### Mode: `checkout` vs. `select`
 
-## Data Structure for `table` prop
+The `mode` prop changes the call-to-action button to fit different use cases.
 
-The `table` prop expects an object with a specific structure, `TPricingTableExpanded`. Here's a simplified overview of what it contains:
+-   **`mode='checkout'` (Default):** The button text will be context-aware, showing labels like "Subscribe" or "Start Trial". This mode is intended for when the user's click should immediately initiate the payment or checkout process.
 
-- **`id`**: A unique identifier for the pricing table.
-- **`livemode`**: A boolean indicating if the table is in live or test mode.
-- **`currency`**: A default currency object.
-- **`items`**: An array of `TPricingTableItem` objects. Each item represents a single plan and contains:
-  - **`price_id`**: The unique ID for the price.
-  - **`product`**: An object with product details like `name`, `description`, and an array of `features`.
-  - **`price`**: An object with pricing details, including `unit_amount`, `currency_options`, and a `recurring` object that specifies the billing `interval` (e.g., 'month', 'year') and `interval_count`.
-  - **`is_highlight`** (optional): A boolean to highlight a specific plan.
-  - **`highlight_text`** (optional): Text to display in the highlight chip (e.g., "Most Popular").
+-   **`mode='select'`:** The button text will show "Select" or "Selected". This is useful when the pricing table is part of a larger form or multi-step process. The `onSelect` callback can be used to update the application's state with the chosen plan, and the UI will visually indicate which plan is currently selected.
 
-### Example `table` Object
+### Handling `onSelect`
 
-```json
-{
-  "id": "pt_12345",
-  "livemode": true,
-  "currency": { "id": "usd", "symbol": "$" },
-  "items": [
-    {
-      "price_id": "price_basic_monthly",
-      "product": {
-        "name": "Basic Plan",
-        "description": "For individuals and small teams.",
-        "features": [
-          { "name": "5 Projects" },
-          { "name": "Basic Analytics" },
-          { "name": "24/7 Support" }
-        ],
-        "unit_label": "user"
-      },
-      "price": {
-        "unit_amount": "1000",
-        "currency_options": [{ "currency_id": "usd", "unit_amount": "1000" }],
-        "recurring": { "interval": "month", "interval_count": 1 }
-      },
-      "is_highlight": false
-    },
-    {
-      "price_id": "price_pro_yearly",
-      "product": {
-        "name": "Pro Plan",
-        "description": "For growing businesses.",
-        "features": [
-          { "name": "Unlimited Projects" },
-          { "name": "Advanced Analytics" },
-          { "name": "Priority Support" }
-        ],
-        "unit_label": "user"
-      },
-      "price": {
-        "unit_amount": "25000",
-        "currency_options": [{ "currency_id": "usd", "unit_amount": "25000" }],
-        "recurring": { "interval": "year", "interval_count": 1 }
-      },
-      "is_highlight": true,
-      "highlight_text": "Popular"
-    }
-  ]
-}
-```
+The `onSelect` callback is the core mechanism for handling user interaction. It's an async function that receives the `priceId` and `currencyId` of the chosen plan. Your application logic should reside here. Common actions include:
 
-This component streamlines the creation of dynamic and interactive pricing pages. Once the user selects a plan, you can use the `onSelect` callback to guide them to the next step, which is often displaying a [PaymentSummary](./components-ui-payment-summary.md).
+-   Storing the selected plan in your application's state.
+-   Redirecting the user to a dedicated checkout page, passing the `priceId` as a URL parameter.
+-   Using the `priceId` to create a checkout session with the payment service backend and then opening a payment form.

package/docs/components-ui.md

@@ -1,44 +1,71 @@
 # UI Components
 
-The UI Components are a collection of granular, self-contained React components designed for building custom payment and checkout experiences. Unlike the high-level [Checkout Components](./components-checkout.md), which manage an entire payment flow, UI Components give you full control over the layout and user experience by providing the essential building blocks for your interface.
-
-This approach allows you to integrate payment functionality seamlessly into your existing application design. You can combine these components to construct a checkout process that is tailored to your specific requirements, as illustrated in the workflow below.
-
-```d2
-direction: down
-
-A: "Display PricingTable Component"
-B: "User Selects a Subscription Plan"
-C: "Application State is Updated via onSelect Callback"
-D: "Render PaymentSummary with Order Details"
-E: "Render Form Elements (e.g., AddressForm)"
-F: "User Clicks Custom 'Pay' Button"
-G: "Application Logic Submits Payment to Backend"
-
-A -> B: "User Action"
-B -> C: "Triggers Callback"
-C -> D: "Re-renders UI"
-D -> E
-E -> F: "User provides info"
-F -> G: "Initiates Submission"
-```
+The `@blocklet/payment-react` library provides a set of granular UI Components designed to give you maximum flexibility when building your payment and checkout interfaces. Unlike the high-level [Checkout Components](./components-checkout.md), which encapsulate entire flows, these components are the building blocks for creating a custom user experience.
 
-Below is an overview of the core UI components available. Each component has its own detailed documentation page.
+These components are ideal when you need to integrate payment functionality into an existing application layout or when the standard checkout flows do not meet your specific design requirements.
 
 <x-cards data-columns="3">
-  <x-card data-title="PricingTable" data-href="/components/ui/pricing-table" data-icon="lucide:table">
-    Renders a structured, responsive table of your subscription plans. It handles logic for switching between billing intervals and currencies, allowing users to make a selection.
+  <x-card data-title="PricingTable" data-icon="lucide:layout-list" data-href="/components/ui/pricing-table">
+    Display subscription plans and pricing options in a structured table, allowing users to select a plan and proceed to checkout.
   </x-card>
-  <x-card data-title="PaymentSummary" data-href="/components/ui/payment-summary" data-icon="lucide:receipt">
-    Displays a detailed breakdown of an order, including line items, quantities, pricing, trial information, and the total amount due. Essential for transparency during checkout.
+  <x-card data-title="PaymentSummary" data-icon="lucide:receipt" data-href="/components/ui/payment-summary">
+    Show a detailed summary of an order, including line items, totals, and trial information within the checkout flow.
   </x-card>
-  <x-card data-title="Form Elements" data-href="/components/ui/form-elements" data-icon="lucide:pencil-ruler">
-    A suite of individual inputs for collecting user data like billing addresses and phone numbers. They include built-in validation and are designed to be composed into any form.
+  <x-card data-title="Form Elements" data-icon="lucide:form-input" data-href="/components/ui/form-elements">
+    A collection of specialized input components for building custom payment and contact information forms, such as address, phone, and country selection.
   </x-card>
 </x-cards>
 
-By combining these components, you can build a robust and user-friendly payment interface that fits perfectly within your application's design. To get started, explore the documentation for the component that best fits your immediate needs.
+## Composing Your Payment UI
+
+UI Components are meant to be composed together to construct a complete payment page. Most of these components require access to the payment context for data like payment methods and settings, so they must be rendered within a `PaymentProvider`.
+
+Below is a conceptual example of how you might combine `PricingTable` and `PaymentSummary` to create a custom checkout page.
+
+```jsx A Custom Checkout Page icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { PricingTable, PaymentSummary } from '@blocklet/payment-react/components';
+// The useSessionContext hook is defined in the PaymentProvider documentation
+import { useSessionContext } from '/path/to/session/context'; 
+
+function CustomCheckoutPage() {
+  const { session, connectApi } = useSessionContext();
+  
+  // In a real application, you would fetch this data from your backend
+  const pricingData = { /* ... pricing table data object ... */ };
+  const selectedItems = [ /* ... line items based on user selection ... */ ];
+  const currency = { /* ... currency object ... */ };
+
+  const handleSelect = (priceId, currencyId) => {
+    console.log('User selected plan:', priceId, 'with currency:', currencyId);
+    // Add the selected plan to the 'selectedItems' state and update the UI
+  };
+
+  return (
+    <PaymentProvider
+      apiHost={connectApi}
+      sessionId={session.user?.did}
+      locale="en"
+    >
+      <div className="checkout-container" style={{ display: 'flex', gap: '2rem' }}>
+        <div className="pricing-section" style={{ flex: 2 }}>
+          <h2>Choose Your Plan</h2>
+          <PricingTable table={pricingData} onSelect={handleSelect} />
+        </div>
+        <div className="summary-section" style={{ flex: 1 }}>
+          <h2>Order Summary</h2>
+          <PaymentSummary items={selectedItems} currency={currency} />
+        </div>
+      </div>
+    </PaymentProvider>
+  );
+}
+```
+
+In this example, `PricingTable` and `PaymentSummary` are used together on a custom page. The `PaymentProvider` wraps the entire structure, making payment settings and methods available to all child components.
+
+## Next Steps
 
----
+Now that you understand the role of UI Components, dive into the specifics of each one to start building your custom payment flow. We recommend starting with the `PricingTable`.
 
-Next, learn how to display your products and plans with the [PricingTable component](./components-ui-pricing-table.md).
+[Learn about the PricingTable component &rarr;](./components-ui-pricing-table.md)