@blocklet/payment-react 1.19.23 → 1.20.1

package/docs/components-checkout-checkout-form.md

@@ -0,0 +1,185 @@
+# CheckoutForm
+
+The `CheckoutForm` component is the primary entry point for rendering a complete payment or donation flow. It orchestrates the entire checkout process by fetching session details and rendering the appropriate user interface based on the provided configuration. It requires a `paymentLink` ID (starting with `plink_`) or a `checkoutSession` ID (starting with `cs_`) to initialize.
+
+This component is highly flexible and can be rendered in several modes, including as an inline element, a standalone full-page experience, or a popup modal.
+
+## How It Works
+
+The `CheckoutForm` component follows a clear internal logic to manage the checkout process. It starts by identifying the type of ID provided, fetches the necessary data, and then renders the appropriate form (`Payment` or `DonationForm`) to handle user interaction.
+
+```d2
+direction: down
+
+A: "CheckoutForm Component Mounted"
+B: "Analyze 'id' prop prefix"
+C: "Call startFromPaymentLink API"
+D: "Call fetchCheckoutSession API"
+E: "Receive CheckoutContext"
+F: "Check 'formType' prop"
+G: "Render <Payment /> component"
+H: "Render <DonationForm /> component"
+I: "User completes payment flow"
+J: "Payment successful?"
+K: "Execute onPaid callback"
+L: "Execute onError callback"
+
+A -> B
+B -> C: "'plink_...'"
+B -> D: "'cs_...'"
+C -> E
+D -> E
+E -> F
+F -> G: "'payment' (default)"
+F -> H: "'donation'"
+G -> I
+H -> I
+I -> J
+J -> K: "Yes"
+J -> L: "No"
+```
+
+## Props
+
+The `CheckoutForm` accepts the following props to customize its behavior and appearance.
+
+| Prop          | Type                                                                        | Description                                                                                                                                      |
+|---------------|-----------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| `id`          | `string`                                                                    | **Required.** The unique identifier for the checkout. Must start with `plink_` for a Payment Link or `cs_` for a Checkout Session.               |
+| `mode`        | `'standalone' \| 'inline' \| 'popup' \| 'inline-minimal' \| 'popup-minimal'` | The display mode. Defaults to `'inline'`.                                                                                                          |
+| `formType`    | `'payment' \| 'donation'`                                                | The type of form to render. Use `'donation'` for a donation-specific UI. Defaults to `'payment'`.                                              |
+| `onPaid`      | `(res: CheckoutContext) => void`                                            | Callback function executed upon successful payment. It receives the final checkout context.                                                      |
+| `onError`     | `(err: Error) => void`                                                      | Callback function executed when an error occurs during the process.                                                                              |
+| `onChange`    | `(data: CheckoutFormData) => void`                                          | Optional. Callback executed when form data (e.g., selected currency) changes.                                                                  |
+| `goBack`      | `() => void`                                                                | Optional. A function to handle a "back" button action, useful in multi-step flows.                                                               |
+| `extraParams` | `Record<string, any>`                                                       | Optional. An object of extra parameters to be sent when initializing a session from a Payment Link.                                              |
+| `action`      | `string`                                                                    | Optional. A string to customize button text or other UI elements based on the action being performed (e.g., 'subscribe', 'donate').                |
+| `theme`       | `'default' \| 'inherit' \| object`                                          | The theme to apply. `'default'` uses the built-in theme, `'inherit'` uses the parent theme, and an object allows for custom Material-UI theme options. |
+| `formRender`  | `Record<string, any>`                                                       | Optional. Used with `formType='donation'` to inject custom render elements or callbacks, such as a custom cancel button.                         |
+
+## Usage
+
+### Prerequisite: Wrapping with PaymentProvider
+
+To use `CheckoutForm`, your application must be wrapped with the `PaymentProvider`. This provider is essential as it supplies the necessary context, including API configuration and session information, to all nested payment components.
+
+A common pattern is to integrate `PaymentProvider` with your application's existing session management. In the example below, `useSessionContext` is a placeholder for your own custom hook that provides the user session. This setup ensures that `CheckoutForm` has access to user data when needed.
+
+For a complete guide on setting up the `PaymentProvider` and creating your `useSessionContext` hook, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+
+```tsx
+import { PaymentProvider } from '@blocklet/payment-react';
+import { CheckoutForm } from '@blocklet/payment-react';
+// This is a placeholder for your application's session context hook.
+// See the PaymentProvider documentation for implementation details.
+import { useSessionContext } from '../hooks/session-context';
+
+// Your main application component
+function App() {
+  const { session, connectDid, disconnectDid } = useSessionContext();
+
+  return (
+    <PaymentProvider
+      apiHost="https://your-api-host"
+      // Pass session and connection handlers from your local context
+      session={session}
+      connect={connectDid}
+      disconnectDid={disconnectDid}>
+      <MyCheckoutPage />
+    </PaymentProvider>
+  );
+}
+
+// A component that renders the checkout form
+function MyCheckoutPage() {
+  const { session } = useSessionContext();
+  const paymentLinkId = 'plink_xxxxxxxxxxxx';
+
+  // Conditionally render based on user login status
+  if (!session?.user) {
+    return <p>Please log in to proceed with the payment.</p>;
+  }
+
+  return (
+    <CheckoutForm
+      id={paymentLinkId}
+      onPaid={() => console.log('Payment successful!')}
+      onError={(err) => console.error('Payment failed:', err)}
+    />
+  );
+}
+```
+
+### Standard Inline Payment
+
+This is the default behavior. The component renders directly where it's placed in the DOM, which is suitable for embedding the payment form within a product or pricing page.
+
+```tsx
+import { CheckoutForm } from '@blocklet/payment-react';
+
+export default function InlinePayment() {
+  return (
+    <div>
+      <h2>Complete Your Purchase</h2>
+      <CheckoutForm
+        id="plink_xxxxxxxxxxxx"
+        mode="inline"
+        onPaid={(data) => {
+          console.log('Payment successful:', data.checkoutSession.id);
+        }}
+        onError={(err) => console.error('Payment failed:', err)}
+      />
+    </div>
+  );
+}
+```
+
+### Standalone Checkout Page
+
+By setting `mode='standalone'`, the component will render a full-page checkout experience, including a header and footer. This is ideal for redirecting users to a dedicated payment page.
+
+```tsx
+import { CheckoutForm } from '@blocklet/payment-react';
+
+export default function StandaloneCheckoutPage() {
+  return (
+    <CheckoutForm
+      id="cs_xxxxxxxxxxxx"
+      mode="standalone"
+      onPaid={(data) => {
+        // Redirect to a success page
+        window.location.href = `/payment-success?session_id=${data.checkoutSession.id}`;
+      }}
+      onError={(err) => console.error('Payment failed:', err)}
+    />
+  );
+}
+```
+
+### Donation Form
+
+To render a UI optimized for donations, set `formType='donation'`. This changes the layout and terminology to better suit a donation flow.
+
+```tsx
+import { CheckoutForm } from '@blocklet/payment-react';
+
+export default function DonationPage() {
+  return (
+    <div>
+      <h2>Support Our Cause</h2>
+      <CheckoutForm
+        id="plink_donation_xxxxxxxx"
+        formType="donation"
+        onPaid={(data) => {
+          console.log(`Thank you for your donation! Invoice ID: ${data.checkoutSession.invoice_id}`);
+        }}
+        onError={(err) => {
+          console.error('Donation failed:', err);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+After integrating the checkout form, you may want to display a summary of the items being purchased. To learn more, see the documentation for the [PaymentSummary](./components-ui-payment-summary.md) component.

package/docs/components-checkout-checkout-table.md

@@ -0,0 +1,228 @@
+# CheckoutTable
+
+The `CheckoutTable` component provides a complete, out-of-the-box solution for displaying a pricing table and handling the entire checkout flow. It fetches pricing table data by ID, allows users to select a plan, and then either redirects them to a checkout page or renders an inline payment form.
+
+This component is a high-level abstraction that internally uses [`PricingTable`](./components-ui-pricing-table.md) for display and [`CheckoutForm`](./components-checkout-checkout-form.md) for payment processing, simplifying the integration of subscription or one-time payment flows.
+
+## How It Works
+
+The component follows a clear, logical flow to guide the user from plan selection to payment completion.
+
+```d2
+direction: down
+
+CheckoutTable: {
+  label: "CheckoutTable Mounted with 'id'"
+  shape: step
+}
+
+FetchData: {
+  label: "Fetch Pricing Table Data"
+  shape: step
+}
+
+DisplayPricing: {
+  label: "Display PricingTable"
+  shape: step
+}
+
+DisplayError: {
+  label: "Display Error Message"
+  shape: step
+  style: {
+    stroke: "#d32f2f"
+  }
+}
+
+HandleSelect: {
+  label: "User selects a plan (handleSelect)"
+  shape: step
+}
+
+CreateSession: {
+  label: "Create Checkout Session via API"
+  shape: step
+}
+
+ModeCheck: {
+  label: "mode === 'standalone'?"
+  shape: diamond
+}
+
+Redirect: {
+  label: "Redirect to Checkout URL"
+  shape: step
+  style: {
+    fill: "#e8f5e9"
+  }
+}
+
+UpdateHash: {
+  label: "Update URL hash with Session ID"
+  shape: step
+}
+
+RenderForm: {
+  label: "Render CheckoutForm"
+  shape: step
+}
+
+OnPaid: {
+  label: "onPaid() callback"
+  shape: step
+  style: {
+    fill: "#e8f5e9"
+  }
+}
+
+OnError: {
+  label: "onError() callback"
+  shape: step
+  style: {
+    stroke: "#d32f2f"
+  }
+}
+
+ToastError: {
+  label: "Show Toast Error"
+  shape: step
+  style: {
+    stroke: "#d32f2f"
+  }
+}
+
+CheckoutTable -> FetchData
+FetchData -> DisplayPricing: "Success"
+FetchData -> DisplayError: "Error"
+DisplayPricing -> HandleSelect
+HandleSelect -> CreateSession
+CreateSession -> ModeCheck: "Success"
+CreateSession -> ToastError: "Error"
+ModeCheck -> Redirect: "Yes"
+ModeCheck -> UpdateHash: "No (Embedded)"
+UpdateHash -> RenderForm
+RenderForm -> OnPaid: "Payment Success"
+RenderForm -> OnError: "Payment Error"
+```
+
+## Props
+
+The `CheckoutTable` component requires a `PaymentProvider` to be present in the component tree. For more details, refer to the [`PaymentProvider`](./providers-payment-provider.md) documentation.
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | Yes | The ID of the pricing table to display. This must start with `prctbl_`. |
+| `mode` | `'standalone' \| 'embedded'` | No | Determines the checkout behavior. In `'standalone'` mode, the user is redirected to a separate checkout page. In `'embedded'` mode (default), the `CheckoutForm` is rendered inline, replacing the pricing table. |
+| `onPaid` | `(data: TCheckout) => void` | No | Callback function executed when the payment is successfully completed. It receives the final checkout session data. |
+| `onError` | `(err: Error) => void` | No | Callback function executed if an error occurs during the payment process. |
+| `onChange` | `(session: TCheckout) => void` | No | Callback function executed whenever the checkout session state changes (e.g., from `pending` to `processing`). |
+| `extraParams` | `object` | No | An object containing extra query parameters to be sent when creating the checkout session. |
+| `goBack` | `() => void` | No | A function that is called when the user clicks the "back" button on the `CheckoutForm`. This enables navigation back to the pricing table view in embedded mode. |
+| `theme` | `object \| 'inherit'` | No | A custom Material-UI theme object to style the component. Set to `'inherit'` to use the ambient theme without an additional `ThemeProvider`. |
+
+## Usage Scenarios
+
+`CheckoutTable` can be configured for two primary user experiences: a full-page redirect or a seamless embedded flow.
+
+> **Note on Context:** The following examples assume you have set up a session context in your application. The `PaymentProvider` relies on this context to get authentication and API details. For a complete guide on this setup, please see the [`PaymentProvider`](./providers-payment-provider.md) documentation.
+
+### Standalone Mode
+
+In `standalone` mode, the component handles plan selection and then redirects the user to a dedicated, hosted checkout page. This is the simplest way to integrate.
+
+```jsx
+import { CheckoutTable, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../contexts/session'; // Path to your custom session context hook
+
+function MyPaymentPage() {
+  const { session, connectApi } = useSessionContext();
+
+  if (!session.user) {
+    return <p>Please log in to see pricing.</p>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <div style={{ height: '600px', width: '100%' }}>
+        <CheckoutTable
+          id="prctbl_xxxxxxxxxxxx" // Replace with your actual pricing table ID
+          mode="standalone"
+        />
+      </div>
+    </PaymentProvider>
+  );
+}
+```
+
+When a user clicks a subscription button in the pricing table, `window.location.replace` is called to navigate them to the checkout URL provided by the payment service API.
+
+### Embedded Mode
+
+In `embedded` mode (the default behavior), the entire checkout process happens within your application. After a plan is selected, the pricing table is replaced by the `CheckoutForm` component.
+
+This mode relies on the URL hash (`#`) to store and retrieve the checkout session ID, enabling a smooth, single-page application experience.
+
+```jsx
+import { CheckoutTable, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../contexts/session'; // Path to your custom session context hook
+import type { TCheckout } from '@blocklet/payment-types';
+
+function MyEmbeddedCheckout() {
+  const { session, connectApi } = useSessionContext();
+
+  const handlePaymentSuccess = (checkoutData: TCheckout) => {
+    console.log('Payment successful!', checkoutData);
+    alert('Thank you for your payment!');
+  };
+
+  const handlePaymentError = (error: Error) => {
+    console.error('Payment failed:', error);
+    alert('There was an issue with your payment.');
+  };
+
+  const handleGoBack = () => {
+    // The component handles clearing the URL hash internally.
+    // You can add custom logic here if needed.
+    console.log('User returned to the pricing table view.');
+  };
+
+  if (!session.user) {
+    return <p>Please log in to see pricing.</p>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <div style={{ height: '800px', width: '100%' }}>
+        <CheckoutTable
+          id="prctbl_xxxxxxxxxxxx" // Replace with your actual pricing table ID
+          onPaid={handlePaymentSuccess}
+          onError={handlePaymentError}
+          goBack={handleGoBack}
+        />
+      </div>
+    </PaymentProvider>
+  );
+}
+```
+
+In this example:
+- The `onPaid` and `onError` callbacks are used to handle the final state of the transaction.
+- The `goBack` prop enables a back button on the payment form, allowing users to return to the plan selection screen without losing context.
+
+## `CheckoutTable` vs. `PricingTable`
+
+It's important to understand the difference between `CheckoutTable` and the lower-level `PricingTable` component to choose the right one for your needs.
+
+#### CheckoutTable
+
+A high-level, all-in-one component that manages the entire checkout flow. It handles data fetching, plan selection, and payment form rendering.
+
+**Use when:** You need a complete, ready-to-use pricing and checkout solution with minimal configuration.
+
+#### PricingTable
+
+A low-level, presentational component that only displays pricing data passed to it. It does not manage state or handle the checkout process.
+
+**Use when:** You need to build a custom checkout flow or display pricing plans in a non-checkout context.
+
+For most use cases, **`CheckoutTable` is the recommended starting point** as it provides a complete and integrated experience. If you find you need more granular control over the user flow, you can then use `PricingTable` and `CheckoutForm` as separate building blocks.

package/docs/components-checkout.md

@@ -0,0 +1,131 @@
+# 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.
+
+These components act as orchestrators for the payment process, as illustrated below:
+
+```d2
+direction: down
+
+user_journey: {
+  action: "User Initiates Action"
+  select_flow: "Selects Checkout Flow" { shape: diamond }
+  action -> select_flow
+}
+
+checkout_components: "Checkout Components" {
+  shape: package
+  form: "CheckoutForm"
+  table: "CheckoutTable"
+  donate: "CheckoutDonate"
+}
+
+payment_flow: "Payment Flow" {
+  ui: "Payment UI"
+  plan: "Plan Selection"
+  dialog: "Donation Dialog"
+  completion: "Payment Completion"
+  ui -> completion
+}
+
+select_flow -> checkout_components.form: "Direct Payment"
+select_flow -> checkout_components.table: "Select Plan"
+select_flow -> checkout_components.donate: "Make Donation"
+
+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"
+```
+
+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.
+
+---
+
+<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.
+  </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.
+  </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>
+</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).

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

@@ -0,0 +1,98 @@
+# 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.
+
+This component must be used within a `PaymentProvider` to access the necessary session and context information.
+
+## Props
+
+The `CreditGrantsList` component accepts the following props to customize its behavior and filter the displayed data.
+
+| 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 Example
+
+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.
+
+For a detailed guide on setting up `PaymentProvider` and creating a `useSessionContext` hook, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+
+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 = () => {
+  const { session, connectApi } = useSessionContext();
+
+  // Render the PaymentProvider only when the session is ready.
+  if (!session) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <MyCreditGrantsPage />
+    </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
+
+The component renders a table with the following columns, providing a detailed overview of each credit grant:
+
+- **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.
+
+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:
+
+| Status    | Color   |
+|-----------|---------|
+| `granted` | Success |
+| `pending` | Warning |
+| `expired` | Default |
+| `depleted`| Default |
+| `voided`  | Default |
+
+---
+
+Next, you can explore how to display a detailed log of credit usage with the [CreditTransactionsList](./components-history-credit-transactions-list.md) component.