@blocklet/payment-react 1.22.32 → 1.23.1

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

@@ -1,95 +1,55 @@
 # CheckoutDonate
 
-The `CheckoutDonate` component provides a flexible and easy-to-integrate solution for adding donation functionality to your application. It supports various display modes, from a simple button that opens a checkout dialog to a fully custom UI that you control.
+This document provides a detailed guide to implementing the `CheckoutDonate` component, a flexible solution for adding donation functionality to your application. By following these steps, you will learn how to configure the component, set up the required providers, and utilize its various display modes to create a seamless donation experience.
 
-This component must be wrapped within both a `PaymentProvider` and a `DonateProvider` to function correctly. The `DonateProvider` manages the settings and state for donation instances within a specific scope of your application.
+The `CheckoutDonate` component is designed to be highly customizable, supporting everything from a simple donation button to a fully bespoke user interface. It must be wrapped within both a `PaymentProvider` and a `DonateProvider` to manage state and connect to the payment backend.
 
-## How It Works
-
-The donation flow is orchestrated by a combination of `DonateProvider` and `CheckoutDonate`. Here's a high-level overview:
-
-```d2 How It Works icon=graph-ql:diagram
-direction: down
-
-user: {
-  shape: c4-person
-}
-
-app: {
-  label: "Your React App"
-  
-  checkout-donate: {
-    label: "CheckoutDonate"
-  }
-  
-  checkout-form: {
-    label: "CheckoutForm (in Dialog)"
-  }
-}
-
-payment-api: {
-  label: "Payment Backend API"
-  shape: cylinder
-}
+## Provider Setup
 
-# Initial Load
-app.checkout-donate -> payment-api: "Fetches settings & supporters"
-
-# Donation Flow
-user -> app.checkout-donate: "1. Clicks Donate"
-app.checkout-donate -> app.checkout-form: "2. Opens Dialog with CheckoutForm"
-app.checkout-form -> payment-api: "3. Processes Payment"
-payment-api -> app.checkout-form: "4. Returns Success"
-app.checkout-form -> app.checkout-donate: "5. Triggers onPaid callback"
-app.checkout-donate -> payment-api: "6. Refetches supporters list"
-payment-api -> app.checkout-donate: "7. Returns updated supporters"
-```
+Correctly setting up the `PaymentProvider` and `DonateProvider` is a prerequisite for using `CheckoutDonate`. The `PaymentProvider` handles the connection to the payment service, while the `DonateProvider` manages the configuration and state for donation instances within a specific part of your application.
 
-1.  **Initialization**: `DonateProvider` fetches and caches donation settings (like preset amounts, button text) from the backend, identified by a unique `mountLocation`.
-2.  **Rendering**: `CheckoutDonate` renders a button or custom UI based on the retrieved settings and its props.
-3.  **Interaction**: When a user initiates a donation, `CheckoutDonate` opens a dialog containing a `CheckoutForm` pre-configured for the donation.
-4.  **Payment**: The user completes the payment through the `CheckoutForm`.
-5.  **Confirmation**: After a successful payment, the `onPaid` callback is triggered, and the component automatically refreshes the list of supporters.
+The following diagram illustrates how these providers wrap the `CheckoutDonate` component and interact with the payment backend and your application's session context.
 
-## Provider Setup
+<!-- DIAGRAM_IMAGE_START:flowchart:4:3:1765377352 -->
+![CheckoutDonate](assets/diagram/components-checkout-checkout-donate-01.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
-Before using `CheckoutDonate`, you must wrap your component tree with `PaymentProvider` and `DonateProvider`.
+The example below demonstrates the required provider structure. The `DonateProvider` is configured with a unique `mountLocation` to distinguish this donation context from others in your application.
 
-```tsx Provider Setup Example icon=logos:react
+```javascript ProviderSetup.jsx icon=logos:react
 import {
   PaymentProvider,
   DonateProvider,
   CheckoutDonate,
 } from '@blocklet/payment-react';
-import { useSessionContext } from '../hooks/session-context'; // Your session context hook
+import { useSessionContext } from '../hooks/session-context'; // This is your app's session context hook
 
-function DonationPage() {
-  const { session, connect } = useSessionContext();
+function DonationSection() {
+  const { session, connectApi } = useSessionContext();
 
-  // Ensure session is loaded before rendering providers
   if (!session) {
-    return <div>Loading...</div>;
+    return <div>Loading session...</div>;
   }
 
   return (
-    <PaymentProvider session={session} connect={connect}>
+    <PaymentProvider session={session} connectApi={connectApi}>
       <DonateProvider
-        mountLocation="unique-page-identifier" // A unique key for this donation context
-        description="Donation for my awesome blog post"
+        mountLocation="blog-post-donations"
+        description="Handles all donations for blog posts"
         defaultSettings={{
           btnText: 'Support Me',
+          historyType: 'avatar',
         }}>
-        {/* Your CheckoutDonate component goes here */}
-        <CheckoutDonate 
+        <CheckoutDonate
           settings={{
-            target: "post-123",
-            title: "Support the Author",
-            description: "If you find this article helpful, feel free to buy me a coffee",
-            reference: "https://your-site.com/posts/123",
+            target: 'post-123',
+            title: 'Support the Author',
+            description: 'If you found this article helpful, consider a small donation.',
+            reference: 'https://example.com/posts/123',
             beneficiaries: [
               {
-                address: "z2qa...",
-                share: "100",
+                address: 'z2qa...gCLd', // Author's DID address
+                share: '100',
               },
             ],
           }}
@@ -100,44 +60,87 @@ function DonationPage() {
 }
 ```
 
-For more details, see the [`DonateProvider`](./providers-donate-provider.md) documentation.
+For a more in-depth explanation of its props and functionality, please refer to the [DonateProvider documentation](./providers-donate-provider.md).
 
 ## Component Props
 
-### `DonateProps`
-
-| Prop | Type | Description |
-| --- | --- | --- |
-| `settings` | `CheckoutDonateSettings` | **Required.** Configuration for this specific donation instance. |
-| `onPaid` | `(session) => void` | Optional. Callback function executed after a successful payment. |
-| `onError` | `(error) => void` | Optional. Callback function executed if an error occurs. |
-| `mode` | `'default' \| 'inline' \| 'custom'` | Optional. The rendering mode. Defaults to `'default'`. |
-| `livemode` | `boolean` | Optional. Overrides the `livemode` from `PaymentProvider`. |
-| `timeout` | `number` | Optional. Milliseconds to wait before closing the dialog after payment. Defaults to `5000`. |
-| `theme` | `'default' \| 'inherit' \| object` | Optional. Theme customization options. See the [Theming](./guides-theming.md) guide. |
-| `children` | `(openDialog, donateTotalAmount, supporters, loading, donateSettings) => React.ReactNode` | Optional. A render prop function used only when `mode="custom"`. |
+The `CheckoutDonate` component accepts several props to control its behavior and appearance.
+
+<x-field-group>
+  <x-field data-name="settings" data-type="CheckoutDonateSettings" data-required="true">
+    <x-field-desc markdown>Configuration object for this specific donation instance. See the `CheckoutDonateSettings` section below for details.</x-field-desc>
+  </x-field>
+  <x-field data-name="onPaid" data-type="(session: TCheckoutSessionExpanded) => void" data-required="false">
+    <x-field-desc markdown>Callback function executed after a successful donation. It receives the checkout session details as an argument.</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="(error: Error) => void" data-required="false">
+    <x-field-desc markdown>Callback function executed if an error occurs during the payment process.</x-field-desc>
+  </x-field>
+  <x-field data-name="mode" data-type="'default' | 'inline' | 'custom'" data-default="default" data-required="false">
+    <x-field-desc markdown>Specifies the rendering mode. `'default'` shows a button and supporter list. `'inline'` shows a button that opens a popover. `'custom'` uses a render prop for a completely custom UI.</x-field-desc>
+  </x-field>
+  <x-field data-name="inlineOptions" data-type="object" data-required="false">
+    <x-field-desc markdown>Configuration options specific to the `'inline'` mode.</x-field-desc>
+    <x-field data-name="button" data-type="ButtonType" data-required="false">
+      <x-field-desc markdown>Custom properties for the inline button, such as `text` and `icon`.</x-field-desc>
+    </x-field>
+  </x-field>
+  <x-field data-name="livemode" data-type="boolean" data-required="false">
+    <x-field-desc markdown>Overrides the `livemode` setting from `PaymentProvider`. Set to `true` for live transactions or `false` for test transactions.</x-field-desc>
+  </x-field>
+  <x-field data-name="timeout" data-type="number" data-default="5000" data-required="false">
+    <x-field-desc markdown>The delay in milliseconds before the donation dialog closes automatically after a successful payment.</x-field-desc>
+  </x-field>
+  <x-field data-name="theme" data-type="'default' | 'inherit' | PaymentThemeOptions" data-default="default" data-required="false">
+    <x-field-desc markdown>Controls the component's styling. See the [Theming guide](./guides-theming.md) for more information.</x-field-desc>
+  </x-field>
+  <x-field data-name="children" data-type="function" data-required="false">
+    <x-field-desc markdown>A render prop function used only when `mode` is set to `'custom'`. See the Custom UI Mode example for the function signature.</x-field-desc>
+  </x-field>
+</x-field-group>
 
 ### `CheckoutDonateSettings`
 
-This object is passed to the `settings` prop and defines the core details of the donation.
-
-| Property | Type | Description |
-| --- | --- | --- |
-| `target` | `string` | **Required.** A unique identifier for the donation target (e.g., a post ID, a project name). |
-| `title` | `string` | **Required.** The title displayed at the top of the donation dialog. |
-| `description` | `string` | **Required.** A short description displayed in the donation dialog. |
-| `reference` | `string` | **Required.** A URL related to the donation, used for reference. |
-| `beneficiaries` | `PaymentBeneficiary[]` | **Required.** An array of objects defining who receives the funds. Each object needs an `address` (recipient's DID) and `share` (percentage). |
-| `amount` | `object` | Optional. Configures donation amounts, including `presets` (e.g., `['1', '5', '10']`), a default `preset`, `minimum`, `maximum`, and whether `custom` amounts are allowed. |
-| `appearance` | `object` | Optional. Customizes the look and feel, including `button` (text, icon, variant) and `history` display (`'avatar'` or `'table'`). |
+This object is passed to the `settings` prop and defines the core details of the donation target.
+
+<x-field-group>
+  <x-field data-name="target" data-type="string" data-required="true">
+    <x-field-desc markdown>A unique identifier for the donation target, such as a post ID or project name. This is used to group donations.</x-field-desc>
+  </x-field>
+  <x-field data-name="title" data-type="string" data-required="true">
+    <x-field-desc markdown>The title displayed at the top of the donation dialog.</x-field-desc>
+  </x-field>
+  <x-field data-name="description" data-type="string" data-required="true">
+    <x-field-desc markdown>A brief description of the donation's purpose, shown in the dialog.</x-field-desc>
+  </x-field>
+  <x-field data-name="reference" data-type="string" data-required="true">
+    <x-field-desc markdown>A URL related to the donation target, used for record-keeping and context.</x-field-desc>
+  </x-field>
+  <x-field data-name="beneficiaries" data-type="PaymentBeneficiary[]" data-required="true">
+    <x-field-desc markdown>An array of objects defining the fund recipients. Each object must include an `address` (recipient's DID) and a `share` (percentage).</x-field-desc>
+  </x-field>
+  <x-field data-name="amount" data-type="object" data-required="false">
+    <x-field-desc markdown>Configures the donation amounts. If not provided, it falls back to settings from `DonateProvider` or a system default.</x-field-desc>
+    <x-field data-name="presets" data-type="string[]" data-required="false" data-desc="An array of suggested donation amounts (e.g., ['1', '5', '10'])."></x-field>
+    <x-field data-name="preset" data-type="string" data-required="false" data-desc="The default selected amount from the presets."></x-field>
+    <x-field data-name="minimum" data-type="string" data-required="false" data-desc="The minimum allowed donation amount."></x-field>
+    <x-field data-name="maximum" data-type="string" data-required="false" data-desc="The maximum allowed donation amount."></x-field>
+    <x-field data-name="custom" data-type="boolean" data-required="false" data-desc="Determines if users can enter a custom donation amount."></x-field>
+  </x-field>
+  <x-field data-name="appearance" data-type="object" data-required="false">
+    <x-field-desc markdown>Customizes the component's visual elements.</x-field-desc>
+    <x-field data-name="button" data-type="object" data-required="false" data-desc="Customizes the donation button's `text`, `icon`, `size`, `color`, and `variant`."></x-field>
+    <x-field data-name="history" data-type="object" data-required="false" data-desc="Configures the appearance of the supporter history list. Set `variant` to 'avatar' or 'table'."></x-field>
+  </x-field>
+</x-field-group>
 
 ## Usage Examples
 
 ### Default Mode
 
-This is the simplest way to use `CheckoutDonate`. It renders a button that opens a donation dialog, along with a summary of recent supporters.
+The default mode is the most straightforward implementation. It renders a donation button and a list of recent supporters. Clicking the button opens a dialog where the user can complete the donation.
 
-```tsx Default Donation Button icon=logos:react
+```javascript DefaultMode.jsx icon=logos:react
 import {
   PaymentProvider,
   DonateProvider,
@@ -146,17 +149,17 @@ import {
 import { useSessionContext } from '../hooks/session-context';
 
 function App() {
-  const { session, connect } = useSessionContext();
+  const { session, connectApi } = useSessionContext();
 
   if (!session) {
     return <div>Loading session...</div>;
   }
 
   return (
-    <PaymentProvider session={session} connect={connect}>
+    <PaymentProvider session={session} connectApi={connectApi}>
       <DonateProvider
-        mountLocation="blog-post-123"
-        description="Donations for Blog Post 123"
+        mountLocation="blog-post-donations"
+        description="Donations for the main blog"
         defaultSettings={{
           btnText: 'Buy me a coffee',
           historyType: 'avatar',
@@ -175,7 +178,7 @@ function App() {
             ],
           }}
           onPaid={() => {
-            console.log('Donation successful!');
+            alert('Thank you for your donation!');
           }}
         />
       </DonateProvider>
@@ -186,62 +189,64 @@ function App() {
 
 ### Custom UI Mode
 
-For full control over the user interface, use `mode="custom"` and provide a render prop as the `children`. This function gives you access to the donation state, including the total amount raised and a list of supporters, allowing you to build a completely custom display.
+For complete control over the layout and presentation, use `mode="custom"`. This mode utilizes a render prop passed as the component's `children`. The function provides access to the donation state and methods, allowing you to build a unique user experience.
 
-```tsx Custom Donation UI icon=logos:react
+```javascript CustomMode.jsx icon=logos:react
 import {
   PaymentProvider,
   DonateProvider,
   CheckoutDonate,
 } from '@blocklet/payment-react';
 import { useSessionContext } from '../hooks/session-context';
-import { CircularProgress, Button } from '@mui/material';
+import { CircularProgress, Button, Avatar, Box, Typography } from '@mui/material';
 
 function CustomDonationDisplay() {
-  const { session, connect } = useSessionContext();
+  const { session, connectApi } = useSessionContext();
 
   if (!session) {
     return <div>Loading session...</div>;
   }
 
   const donateSettings = {
-    target: 'post-123',
-    title: 'Support the Author',
-    description: 'If you found this article helpful, consider a small donation.',
-    reference: 'https://example.com/posts/123',
+    target: 'project-alpha',
+    title: 'Support Project Alpha',
+    description: 'Help us build the next generation of tools.',
+    reference: 'https://example.com/projects/alpha',
     beneficiaries: [
       {
-        address: 'z2qa...gCLd', // Author's DID address
+        address: 'z2qa...gCLd',
         share: '100',
       },
     ],
   };
 
   return (
-    <PaymentProvider session={session} connect={connect}>
+    <PaymentProvider session={session} connectApi={connectApi}>
       <DonateProvider
-        mountLocation="blog-post-123"
-        description="Donations for Blog Post 123">
+        mountLocation="project-alpha-donations"
+        description="Donations for Project Alpha">
         <CheckoutDonate mode="custom" settings={donateSettings}>
           {(openDonate, totalAmount, supporters, loading, settings) => (
-            <div style={{ border: '1px solid #ccc', padding: '16px', borderRadius: '8px' }}>
-              <h2>Our Supporters</h2>
-              <p>Total Donations: <strong>{totalAmount}</strong></p>
-              <Button variant="contained" onClick={openDonate}>
+            <Box sx={{ border: '1px solid #e0e0e0', padding: '24px', borderRadius: '8px', textAlign: 'center' }}>
+              <Typography variant="h5">Our Supporters</Typography>
+              <Typography variant="body1" color="text.secondary" sx={{ mb: 2 }}>
+                Total Donated: <strong>{totalAmount}</strong>
+              </Typography>
+              <Button variant="contained" size="large" onClick={openDonate}>
                 {settings?.appearance?.button?.text || 'Donate Now'}
               </Button>
-              {loading ? (
-                <CircularProgress style={{ marginTop: '16px' }} />
-              ) : (
-                <ul style={{ listStyle: 'none', padding: 0, marginTop: '16px' }}>
-                  {(supporters.supporters || []).map((supporter) => (
-                    <li key={supporter.id}>
-                      <span>{supporter.customer?.name}</span>
-                    </li>
+              {loading && <CircularProgress sx={{ display: 'block', margin: '16px auto' }} />}
+              {!loading && (supporters.supporters || []).length > 0 && (
+                <Box sx={{ mt: 3 }}>
+                  {(supporters.supporters || []).slice(0, 5).map((supporter) => (
+                    <Box key={supporter.id} sx={{ display: 'flex', alignItems: 'center', mb: 1 }}>
+                      <Avatar src={supporter.customer?.avatar} sx={{ width: 24, height: 24, mr: 1 }} />
+                      <Typography variant="body2">{supporter.customer?.name}</Typography>
+                    </Box>
                   ))}
-                </ul>
+                </Box>
               )}
-            </div>
+            </Box>
           )}
         </CheckoutDonate>
       </DonateProvider>
@@ -250,10 +255,12 @@ function CustomDonationDisplay() {
 }
 ```
 
-The `children` function receives the following arguments:
+#### Custom Render Prop Arguments
+
+The `children` function provides the following arguments:
 
--   `openDonate`: A function to manually trigger the donation dialog.
--   `totalAmount`: A formatted string of the total amount donated (e.g., `"125.00 T"`).
--   `supporters`: A `DonateHistory` object containing the `supporters` array and currency info.
--   `loading`: A boolean indicating if the supporter data is being fetched.
--   `settings`: The resolved donation settings, merged from `DonateProvider` and props.
+-   `openDonate()`: A function to programmatically open the donation dialog.
+-   `donateTotalAmount`: A formatted string representing the total amount donated (e.g., `"125.00 T"`).
+-   `supporters`: A `DonateHistory` object containing the `supporters` array, total amount, currency, and method details.
+-   `loading`: A boolean that is `true` while supporter data is being fetched.
+-   `donateSettings`: The final, resolved donation settings, merged from `DonateProvider` and the component's `settings` prop.

package/docs/components-checkout-checkout-donate.zh-TW.md

@@ -8,42 +8,9 @@
 
 捐贈流程由 `DonateProvider` 和 `CheckoutDonate` 共同協調。以下是高層次的概述：
 
-```d2 How It Works icon=graph-ql:diagram
-direction: down
-
-user: {
-  shape: c4-person
-}
-
-app: {
-  label: "您的 React 應用程式"
-  
-  checkout-donate: {
-    label: "CheckoutDonate"
-  }
-  
-  checkout-form: {
-    label: "CheckoutForm (在對話方塊中)"
-  }
-}
-
-payment-api: {
-  label: "支付後端 API"
-  shape: cylinder
-}
-
-# 初始載入
-app.checkout-donate -> payment-api: "獲取設定和支持者"
-
-# 捐贈流程
-user -> app.checkout-donate: "1. 點擊捐贈"
-app.checkout-donate -> app.checkout-form: "2. 開啟帶有 CheckoutForm 的對話方塊"
-app.checkout-form -> payment-api: "3. 處理支付"
-payment-api -> app.checkout-form: "4. 回傳成功"
-app.checkout-form -> app.checkout-donate: "5. 觸發 onPaid 回呼"
-app.checkout-donate -> payment-api: "6. 重新獲取支持者列表"
-payment-api -> app.checkout-donate: "7. 回傳更新後的支持者"
-```
+<!-- DIAGRAM_IMAGE_START:flowchart:4:3::1765377352 -->
+![CheckoutDonate](assets/diagram/components-checkout-checkout-donate-01.zh-TW.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
 1.  **初始化**：`DonateProvider` 從後端獲取並快取捐贈設定（如預設金額、按鈕文字），並透過唯一的 `mountLocation` 進行識別。
 2.  **渲染**：`CheckoutDonate` 根據檢索到的設定及其 props 渲染按鈕或自訂 UI。

package/docs/components-checkout-checkout-donate.zh.md

@@ -8,42 +8,9 @@
 
 捐赠流程由 `DonateProvider` 和 `CheckoutDonate` 共同协调。以下是其高级概述：
 
-```d2 工作原理 icon=graph-ql:diagram
-direction: down
-
-user: {
-  shape: c4-person
-}
-
-app: {
-  label: "您的 React 应用"
-  
-  checkout-donate: {
-    label: "CheckoutDonate"
-  }
-  
-  checkout-form: {
-    label: "CheckoutForm（在对话框中）"
-  }
-}
-
-payment-api: {
-  label: "支付后端 API"
-  shape: cylinder
-}
-
-# 初始加载
-app.checkout-donate -> payment-api: "获取设置和支持者"
-
-# 捐赠流程
-user -> app.checkout-donate: "1. 点击捐赠"
-app.checkout-donate -> app.checkout-form: "2. 打开带有 CheckoutForm 的对话框"
-app.checkout-form -> payment-api: "3. 处理支付"
-payment-api -> app.checkout-form: "4. 返回成功"
-app.checkout-form -> app.checkout-donate: "5. 触发 onPaid 回调"
-app.checkout-donate -> payment-api: "6. 重新获取支持者列表"
-payment-api -> app.checkout-donate: "7. 返回更新后的支持者"
-```
+<!-- DIAGRAM_IMAGE_START:flowchart:4:3::1765377352 -->
+![CheckoutDonate](assets/diagram/components-checkout-checkout-donate-01.zh.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
 1.  **初始化**：`DonateProvider` 从后端获取并缓存捐赠设置（如预设金额、按钮文本），这些设置由唯一的 `mountLocation` 标识。
 2.  **渲染**：`CheckoutDonate` 根据检索到的设置及其 props 渲染一个按钮或自定义 UI。