@blocklet/payment-react/docs/overview.md

Reusable react components for payment kit v2

# Overview

This document provides a high-level overview of the `@blocklet/payment-react` library. By the end of this guide, you will understand its core features, architecture, and the types of payment functionalities you can build with it. This library is designed to simplify the integration of payment flows, subscriptions, and donation systems into React applications by interfacing with the Blocklet Payment Kit.

## Key Features

The library offers a comprehensive set of tools to accelerate the development of payment-related features.

<x-cards data-columns="2">
  <x-card data-title="Pre-built UI Components" data-icon="lucide:layout-template">
    A suite of ready-to-use components, including checkout forms, pricing tables, and donation widgets, to handle common payment workflows.
  </x-card>
  <x-card data-title="Customizable Themes" data-icon="lucide:palette">
    Leverages Material-UI for theming, allowing for extensive customization to match your application's design system.
  </x-card>
  <x-card data-title="Comprehensive Payment Operations" data-icon="lucide:credit-card">
    Supports a wide range of payment operations such as subscriptions, invoice management, refunds, and metered billing.
  </x-card>
  <x-card data-title="Internationalization (i18n)" data-icon="lucide:languages">
    Includes built-in support for multiple languages, enabling you to create a localized experience for a global user base.
  </x-card>
</x-cards>

## How It Works

`@blocklet/payment-react` operates on a provider-component model. The `PaymentProvider` component is central to the library's functionality. It establishes a React context that manages API communication, state, and session information. All other payment-related components must be nested within a `PaymentProvider` to function correctly. This architecture centralizes critical logic, ensuring that components are decoupled and focused on their specific UI tasks.

The diagram below illustrates the high-level data flow. User interactions with payment components trigger API calls handled by the `PaymentProvider`, which communicates with the Payment Kit backend and updates the UI with the response.

<!-- DIAGRAM_IMAGE_START:architecture:16:9:1765377042 -->
![Overview](assets/diagram/overview-01.jpg)
<!-- DIAGRAM_IMAGE_END -->

## Available Components

The library is organized into several categories of components and utilities to address different aspects of building a payment system.

| Category | Description | Key Components |
| --- | --- | --- |
| **Providers** | Context providers that wrap your application to enable payment features. | `PaymentProvider`, `DonateProvider` |
| **Checkout Components** | High-level components for complete payment and donation flows. | `CheckoutForm`, `CheckoutTable`, `CheckoutDonate` |
| **UI Components** | Granular components for building custom payment user interfaces. | `PricingTable`, `PaymentSummary`, `AddressForm` |
| **History Components** | Components for displaying historical data like invoices and payments. | `CustomerInvoiceList`, `CustomerPaymentList` |
| **Business Logic** | Specialized components for managing subscriptions and overdue payments. | `ResumeSubscription`, `OverdueInvoicePayment` |
| **Hooks & Utilities** | Custom hooks and utility functions for interacting with the payment service. | `useSubscription`, `api`, `dayjs` |

## Next Steps

To begin implementing payment features, proceed to the [Getting Started](./getting-started.md) guide, which provides step-by-step instructions for installation and building a basic payment form.