@blocklet/payment-react 1.20.4 → 1.20.6

package/docs/components-checkout.md

@@ -1,131 +1,65 @@
 # Checkout Components
 
-Checkout components are high-level, pre-built components designed to serve as complete entry points for various payment flows. They encapsulate the entire user experience, from presenting payment options to processing transactions and handling success or error states. This allows you to integrate complex payment scenarios like one-time payments, subscriptions from a pricing table, or donations with minimal setup.
+The `@blocklet/payment-react` library provides a set of high-level Checkout Components designed to serve as complete, ready-to-use entry points for various payment scenarios. These components encapsulate the entire user flow, from selecting a product to completing the payment, allowing you to integrate complex payment experiences with minimal setup.
 
-These components act as orchestrators for the payment process, as illustrated below:
+Whether you need to display a pricing table, accept donations, or process a direct payment link, these components handle the underlying logic of session creation, state management, and UI rendering.
 
-```d2
+### Component Flow
+
+The typical flow involves a user interacting with an entry-point component like `CheckoutTable` or `CheckoutDonate`. These components then create a `CheckoutSession` and delegate the final payment processing to the core `CheckoutForm` component.
+
+```d2 Checkout Component Flow icon=mdi:transit-connection-variant
 direction: down
 
-user_journey: {
-  action: "User Initiates Action"
-  select_flow: "Selects Checkout Flow" { shape: diamond }
-  action -> select_flow
+User: {
+  shape: c4-person
 }
 
-checkout_components: "Checkout Components" {
-  shape: package
-  form: "CheckoutForm"
-  table: "CheckoutTable"
-  donate: "CheckoutDonate"
-}
+Checkout-Flow: {
+  label: "Checkout Flow"
 
-payment_flow: "Payment Flow" {
-  ui: "Payment UI"
-  plan: "Plan Selection"
-  dialog: "Donation Dialog"
-  completion: "Payment Completion"
-  ui -> completion
-}
+  Entry-Points: {
+    label: "User-Facing Components"
+    shape: rectangle
 
-select_flow -> checkout_components.form: "Direct Payment"
-select_flow -> checkout_components.table: "Select Plan"
-select_flow -> checkout_components.donate: "Make Donation"
+    CheckoutTable: {
+      label: "CheckoutTable"
+    }
 
-checkout_components.form -> payment_flow.ui
-checkout_components.table -> payment_flow.plan: "Displays PricingTable"
-payment_flow.plan -> checkout_components.form: "Creates Session & Uses"
-checkout_components.donate -> payment_flow.dialog: "Opens Dialog"
-payment_flow.dialog -> checkout_components.form: "Uses"
-```
+    CheckoutDonate: {
+      label: "CheckoutDonate"
+    }
+  }
+
+  Core-Processor: {
+    label: "Core Payment Processor"
+    shape: rectangle
+
+    CheckoutForm: {
+      label: "CheckoutForm"
+    }
+  }
+}
 
-This section provides an overview of the primary checkout components. For detailed API references and advanced usage, please refer to the specific documentation for each component.
+User -> Checkout-Flow.Entry-Points.CheckoutTable: "Selects a subscription"
+User -> Checkout-Flow.Entry-Points.CheckoutDonate: "Makes a donation"
+Checkout-Flow.Entry-Points.CheckoutTable -> Checkout-Flow.Core-Processor.CheckoutForm: "On plan selection"
+Checkout-Flow.Entry-Points.CheckoutDonate -> Checkout-Flow.Core-Processor.CheckoutForm: "On donate action"
+Checkout-Flow.Core-Processor.CheckoutForm -> User: "Payment Result"
+```
 
----
+Explore the components below to find the best fit for your application's needs.
 
 <x-cards data-columns="3">
   <x-card data-title="CheckoutForm" data-icon="lucide:credit-card" data-href="/components/checkout/checkout-form">
-    The core component for processing payments from a `paymentLink` or `checkoutSession`, managing the entire payment UI and state.
+    The fundamental component for processing payments. It takes a `paymentLink` or `checkoutSession` ID and renders the complete payment UI.
   </x-card>
   <x-card data-title="CheckoutTable" data-icon="lucide:table" data-href="/components/checkout/checkout-table">
-    Renders a pricing table and handles the checkout flow when a user selects a plan. Ideal for subscription-based services.
+    Displays a complete pricing table. When a user selects a plan, it automatically initiates a checkout session and renders the payment form.
   </x-card>
-  <x-card data-title="CheckoutDonate" data-icon="lucide:heart" data-href="/components/checkout/checkout-donate">
-    A flexible component for implementing donations, supporting multiple display modes and managing the donation payment process.
+  <x-card data-title="CheckoutDonate" data-icon="lucide:heart-handshake" data-href="/components/checkout/checkout-donate">
+    A flexible component for adding donation functionality. It handles donation setup, displays supporter history, and manages the donation payment flow.
   </x-card>
 </x-cards>
 
-## Provider Dependencies
-
-All checkout components require being wrapped within the `PaymentProvider` to function correctly, as it supplies the necessary context for API communication and session management.
-
-For `CheckoutDonate`, it is also recommended to wrap it with `DonateProvider` to manage global donation settings and state effectively.
-
-Here is a typical provider setup in an application. This example uses a local session context for DID connect, which is a common pattern.
-
-```tsx
-import React from 'react';
-import { CheckoutTable, CheckoutDonate } from '@blocklet/payment-react';
-import { PaymentProvider } from '@blocklet/payment-react/lib/contexts/payment';
-import { DonateProvider } from '@blocklet/payment-react/lib/contexts/donate';
-
-// This is a local file you would create to manage your DID-Connect session.
-// See the PaymentProvider documentation for setup instructions.
-import { SessionProvider, useSessionContext } from '../contexts/session';
-
-const donationSettings = {
-  target: 'unique_target_id_for_your_project',
-  title: 'Support Our Project',
-  description: 'Your contribution helps us continue our work.',
-  beneficiaries: [{ did: 'z2qa...', weight: 100 }], // Replace with actual beneficiary DID
-};
-
-function MyPaymentFeatures() {
-  // Obtain session and connectApi from your local session context.
-  const { session, connectApi } = useSessionContext();
-
-  return (
-    // PaymentProvider requires the session and connectApi for authentication and communication.
-    <PaymentProvider session={session} connect={connectApi}>
-      {/* Example 1: Using CheckoutTable for subscription plans */}
-      <div style={{ marginBottom: '40px' }}>
-        <h2>Choose a Subscription Plan</h2>
-        <CheckoutTable
-          id="prctbl_xxxxxxxxxxxx" // Replace with your pricing table ID
-          onPaid={(context) => console.log('Subscription successfully started!', context)}
-          onError={(error) => console.error('Subscription failed:', error)}
-        />
-      </div>
-
-      {/* Example 2: Using CheckoutDonate with its specific provider */}
-      <div>
-        <h2>Make a Donation</h2>
-        <DonateProvider>
-          <CheckoutDonate
-            settings={donationSettings}
-            onPaid={() => console.log('Thank you for your donation!')}
-            onError={(error) => console.error('Donation failed:', error)}
-          />
-        </DonateProvider>
-      </div>
-    </PaymentProvider>
-  );
-}
-
-function App() {
-  // The SessionProvider wraps your application to provide session context.
-  // For a detailed guide on setting up your session context and PaymentProvider,
-  // please see the [PaymentProvider documentation](./providers-payment-provider.md).
-  return (
-    <SessionProvider>
-      <MyPaymentFeatures />
-    </SessionProvider>
-  );
-}
-
-export default App;
-```
-
-## Next Steps
-
-These components provide powerful, out-of-the-box solutions for common payment scenarios. To build more customized payment experiences, you can explore the lower-level [UI Components](./components-ui.md).
+Each of these components is designed to be highly customizable and can be integrated seamlessly into your application. Click on any card to view its detailed documentation and usage examples.

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

@@ -1,98 +1,73 @@
 # CreditGrantsList
 
-The `CreditGrantsList` component is designed to display a comprehensive list of credit grants associated with a specific customer. It presents key information such as the grant's status, remaining balance, scope, and effective dates in a clear, tabular format. This component is essential for both customers checking their credit balance and administrators managing credit grants.
+The `CreditGrantsList` component renders a paginated table displaying a customer's credit grants. It provides a clear overview of each grant's status, remaining balance, scope, and validity period.
 
-This component must be used within a `PaymentProvider` to access the necessary session and context information.
+This component is essential for both customer-facing portals where users can track their available credits and admin dashboards for managing customer grants. It must be used within a `PaymentProvider` to access the necessary session and API context.
 
 ## Props
 
-The `CreditGrantsList` component accepts the following props to customize its behavior and filter the displayed data.
+| Prop | Type | Description | Default |
+| --- | --- | --- | --- |
+| `customer_id` | `string` | Optional. The ID of the customer. If omitted, it defaults to the DID of the currently authenticated user from the session context. | `session.user.did` |
+| `subscription_id` | `string` | Optional. Filters the list to show only grants associated with a specific subscription. | `''` |
+| `status` | `string` | Optional. A comma-separated string of statuses to filter by. Valid statuses include `granted`, `pending`, `expired`, `depleted`, and `voided`. | `'granted,pending,depleted,expired'` |
+| `pageSize` | `number` | Optional. The number of items to display per page. | `10` |
+| `onTableDataChange` | `(data, prevData) => void` | Optional. A callback function that is invoked whenever the table data is fetched or updated. | `() => {}` |
+| `mode` | `'dashboard' \| 'portal'` | Optional. Determines the navigation behavior when a row is clicked. Use `'portal'` for customer-facing views and `'dashboard'` for admin panels, which generates different link paths. | `'portal'` |
 
-| Prop                | Type                               | Description                                                                                                                                                                                             |
-|---------------------|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `customer_id`       | `string`                           | The ID of the customer whose credit grants are to be displayed. If not provided, it defaults to the DID of the currently logged-in user from the session context.                                          |
-| `subscription_id`   | `string`                           | Optional. Filters the credit grants to show only those associated with a specific subscription ID.                                                                                                        |
-| `status`            | `string`                           | Optional. A comma-separated string of statuses to filter by. Defaults to `'granted,pending,depleted,expired'`. Valid statuses include `granted`, `pending`, `expired`, `depleted`, and `voided`.          |
-| `pageSize`          | `number`                           | Optional. The number of items to display per page. Defaults to `10`.                                                                                                                                    |
-| `onTableDataChange` | `(data, prevData) => void`         | Optional. A callback function that is invoked when the table's data is fetched or updated. It receives the new and previous data sets as arguments.                                                      |
-| `mode`              | `'dashboard'` \| `'portal'`         | Optional. Determines the navigation behavior. In `'dashboard'` mode (for admins), links navigate to admin-specific routes. In `'portal'` mode (for customers), links navigate to customer-facing routes. |
+## Usage
 
-## Usage Example
+### Basic Usage (For Logged-in Customer)
 
-To use `CreditGrantsList`, it must be wrapped in a `PaymentProvider`. The provider requires `session` and `connectApi` props, which should be supplied by a session context in your application.
+By default, the `CreditGrantsList` component fetches and displays the credit grants for the currently authenticated user. This is the most common use case for a customer's account page.
 
-For a detailed guide on setting up `PaymentProvider` and creating a `useSessionContext` hook, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+```jsx My Credit Grants icon=logos:react
+import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '/path/to/your/session/context'; // Adjust this import path
 
-Below is a typical implementation:
-
-```jsx
-import React from 'react';
-import { PaymentProvider } from '@blocklet/payment-react';
-import CreditGrantsList from '@blocklet/payment-react/lib/components/history/credit-grants-list';
-// This is your local hook to get session context.
-// See the PaymentProvider docs for how to create it.
-import { useSessionContext } from '../../contexts/session';
-
-// A component that displays the credit grants list.
-const MyCreditGrantsPage = () => {
-  // If you don't provide a customer_id, the component will automatically
-  // use the DID of the currently logged-in user.
-  const customerId = 'cus_xxxxxxxxxxxxxx'; // Optional: replace with a specific customer ID
-
-  return (
-    <div>
-      <h2>My Credit Grants</h2>
-      <CreditGrantsList customer_id={customerId} pageSize={5} />
-    </div>
-  );
-};
-
-// Your main App component where you set up the providers.
-const App = () => {
+function MyCreditGrantsPage() {
   const { session, connectApi } = useSessionContext();
 
-  // Render the PaymentProvider only when the session is ready.
-  if (!session) {
+  if (!session || !connectApi) {
     return <div>Loading session...</div>;
   }
 
   return (
     <PaymentProvider session={session} connectApi={connectApi}>
-      <MyCreditGrantsPage />
+      <h2>My Credit Grants</h2>
+      <CreditGrantsList />
     </PaymentProvider>
   );
-};
-
-export default App;
+}
 ```
 
-In this example, the `App` component retrieves `session` and `connectApi` using a local `useSessionContext` hook and passes them to `PaymentProvider`. The `MyCreditGrantsPage` component then renders `CreditGrantsList` within this context, ensuring it has access to the necessary data.
-
-## Displayed Information
+### Admin or Dashboard Usage
 
-The component renders a table with the following columns, providing a detailed overview of each credit grant:
+In an administrative dashboard, you can display the credit grants for any customer by providing the `customer_id` prop. You can also customize the filters and page size.
 
-- **Name**: The name of the credit grant, or its ID if no name is provided.
-- **Status**: The current status of the grant (e.g., `granted`, `pending`, `expired`), displayed using a color-coded chip for easy identification.
-- **Remaining Credit**: The amount of credit still available in the grant, along with the currency symbol.
-- **Scope**: Indicates whether the credit is `general` (applicable to any charge) or `specific` (applicable only to certain prices).
-- **Effective Date**: The date and time when the credit grant becomes active.
-- **Expiration Date**: The date and time when the credit grant expires. A hyphen (`-`) is shown if there is no expiration date.
+```jsx Customer Credit Grants icon=logos:react
+import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '/path/to/your/session/context'; // Adjust this import path
 
-Each row in the table is clickable, navigating the user to a detailed view of that specific credit grant.
-
-## StatusChip Helper
-
-The `CreditGrantsList` utilizes an internal `StatusChip` component to visually represent the status of each grant. The colors are mapped as follows:
+function CustomerDetailsPage({ customerId }) {
+  const { session, connectApi } = useSessionContext();
 
-| Status    | Color   |
-|-----------|---------|
-| `granted` | Success |
-| `pending` | Warning |
-| `expired` | Default |
-| `depleted`| Default |
-| `voided`  | Default |
+  if (!session || !connectApi) {
+    return <div>Loading session...</div>;
+  }
 
----
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <h3>Active Credit Grants for Customer</h3>
+      <CreditGrantsList
+        customer_id={customerId}
+        status="granted,pending"
+        pageSize={5}
+        mode="dashboard"
+      />
+    </PaymentProvider>
+  );
+}
+```
 
-Next, you can explore how to display a detailed log of credit usage with the [CreditTransactionsList](./components-history-credit-transactions-list.md) component.
+This example shows how to list only the 'granted' and 'pending' grants for a specific customer, displaying 5 items per page. The `mode="dashboard"` ensures that clicking a grant will navigate to an admin-specific URL.

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

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