@blocklet/payment-react 1.20.4 → 1.20.6

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

@@ -1,75 +1,98 @@
 # CheckoutDonate
 
-The `CheckoutDonate` component provides a flexible way to implement donation functionality in your application. It supports several display modes, from a simple pre-built button to a fully custom UI, and handles the entire donation flow, including displaying supporter history.
+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.
 
-To function correctly, `CheckoutDonate` must be wrapped within both a [`PaymentProvider`](./providers-payment-provider.md) and a [`DonateProvider`](./providers-donate-provider.md).
+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.
 
-## Props
+## How It Works
 
-| Prop | Type | Description |
-|---|---|---|
-| `settings` | `CheckoutDonateSettings` | **Required.** An object containing the configuration for the donation instance, such as target, title, and beneficiaries. |
-| `onPaid` | `(session: TCheckoutSessionExpanded) => void` | Optional. A callback function that is executed after a donation is successfully paid. |
-| `onError` | `(error: any) => void` | Optional. A callback function that is executed if an error occurs during the payment process. |
-| `livemode` | `boolean` | Optional. Toggles between live and test payment modes. If not set, it inherits the value from `PaymentProvider`. |
-| `timeout` | `number` | Optional. The time in milliseconds to wait before closing the checkout dialog after a successful payment. Defaults to `5000`. |
-| `mode` | `'default' \| 'inline' \| 'custom'` | Optional. Determines the rendering mode of the component. Defaults to `'default'`. |
-| `inlineOptions` | `{ button?: ButtonType }` | Optional. Customization options for the button when `mode` is set to `'inline'`. |
-| `theme` | `'default' \| 'inherit' \| PaymentThemeOptions` | Optional. Controls the component's theme. See the [Theming guide](./guides-theming.md) for more details. Defaults to `'default'`. |
-| `children` | `(openDialog, donateTotalAmount, supporters, loading, donateSettings) => React.ReactNode` | Optional. A render prop function used when `mode` is `'custom'`. See the Custom Mode section for details. |
+The donation flow is orchestrated by a combination of `DonateProvider` and `CheckoutDonate`. Here's a high-level overview:
 
-### `CheckoutDonateSettings`
+```d2 How It Works icon=graph-ql:diagram
+direction: down
 
-This object configures the donation's behavior and appearance.
+user: {
+  shape: c4-person
+}
 
-| Property | Type | Description |
-|---|---|---|
-| `target` | `string` | **Required.** A unique identifier for the donation instance (e.g., a post ID like `"post-123"`). |
-| `title` | `string` | **Required.** The title displayed in the donation modal. |
-| `description` | `string` | **Required.** A description shown in the donation modal. |
-| `reference` | `string` | **Required.** A reference link for the donation, such as the URL of the page where the donation is being made. |
-| `beneficiaries` | `PaymentBeneficiary[]` | **Required.** An array of objects defining who receives the donation and their respective shares. |
-| `amount` | `object` | Optional. Configures donation amounts, including presets, min/max values, and whether custom amounts are allowed. Inherits from `DonateProvider` if not set. |
-| `appearance` | `object` | Optional. Customizes the look and feel of the donation button and supporter history display (`'avatar'` or `'table'`). Inherits from `DonateProvider` if not set. |
-
-## Basic Usage
-
-Here is a basic example of how to set up `CheckoutDonate`. This will render a default donation button and a list of supporters.
-
-```tsx
-import { 
-  PaymentProvider, 
-  DonateProvider, 
-  CheckoutDonate 
+app: {
+  label: "Your React App"
+  
+  checkout-donate: {
+    label: "CheckoutDonate"
+  }
+  
+  checkout-form: {
+    label: "CheckoutForm (in Dialog)"
+  }
+}
+
+payment-api: {
+  label: "Payment Backend API"
+  shape: cylinder
+}
+
+# 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"
+```
+
+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.
+
+## Provider Setup
+
+Before using `CheckoutDonate`, you must wrap your component tree with `PaymentProvider` and `DonateProvider`.
+
+```tsx Provider Setup Example icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
 } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context'; // Your session context hook
 
-// This is a placeholder for your application's session management.
-// See the documentation for PaymentProvider for details on how to set up this context.
-import { useSessionContext } from '../contexts/session'; // Adjust path as needed
+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 (
-    <PaymentProvider session={session} connect={connectApi}>
-      <DonateProvider 
-        mountLocation="unique-page-identifier"
-        description="Donations for this page"
-      >
-        <CheckoutDonate
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="unique-page-identifier" // A unique key for this donation context
+        description="Donation for my awesome blog post"
+        defaultSettings={{
+          btnText: 'Support Me',
+        }}>
+        {/* Your CheckoutDonate component goes here */}
+        <CheckoutDonate 
           settings={{
-            target: "post-123", // Unique ID for this donation target
+            target: "post-123",
             title: "Support the Author",
-            description: "If you find this article helpful, feel free to buy me a coffee.",
+            description: "If you find this article helpful, feel free to buy me a coffee",
             reference: "https://your-site.com/posts/123",
             beneficiaries: [
               {
-                address: "did:abt:z123...", // Beneficiary's DID address
+                address: "z2qa...",
                 share: "100",
               },
             ],
           }}
-          onPaid={(session) => console.log('Donation successful:', session.id)}
         />
       </DonateProvider>
     </PaymentProvider>
@@ -77,123 +100,160 @@ function DonationSection() {
 }
 ```
 
-## Usage Modes
+For more details, see the [`DonateProvider`](./providers-donate-provider.md) documentation.
 
-The `CheckoutDonate` component can be rendered in three different modes, controlled by the `mode` prop.
+## Component Props
 
-### Default Mode
+### `DonateProps`
 
-When `mode` is `'default'` (or omitted), the component renders a donation button. Below the button, it displays a history of supporters, which can be configured to show as avatars or a table via `settings.appearance.history.variant`.
-
-```tsx
-<CheckoutDonate
-  settings={{
-    target: "post-456",
-    title: "Support Our Project",
-    description: "Every little bit helps!",
-    reference: "https://your-site.com/projects/our-project",
-    beneficiaries: [{ address: "did:abt:z456...", share: "100" }],
-    appearance: {
-      button: {
-        text: 'Buy me a coffee ☕',
-        variant: 'contained',
-      },
-      history: {
-        variant: 'table', // or 'avatar'
-      },
-    },
-  }}
-/>
-```
+| 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"`. |
 
-### Inline Mode
-
-Setting `mode="inline"` renders a button that opens a popover when hovered over. The popover contains the donation button and a summary of supporters. This is useful for more compact UIs.
-
-```tsx
-<CheckoutDonate
-  mode="inline"
-  settings={{
-    target: "post-789",
-    title: "Tip Jar",
-    description: "Thanks for your support!",
-    reference: "https://your-site.com/posts/789",
-    beneficiaries: [{ address: "did:abt:z789...", share: "100" }],
-  }}
-  inlineOptions={{
-    button: {
-      text: 'Tip',
-      variant: 'outlined',
-    }
-  }}
-/>
-```
+### `CheckoutDonateSettings`
 
-### Custom Mode
+This object is passed to the `settings` prop and defines the core details of the donation.
 
-For complete control over the UI, use `mode="custom"`. This mode uses a render prop passed as the `children` of the component. The function provides you with the state and actions needed to build your own interface.
+| 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'`). |
 
-The `children` function receives the following arguments:
+## 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.
 
-| Argument | Type | Description |
-|---|---|---|
-| `openDialog` | `() => void` | A function to call to open the donation payment modal. |
-| `donateTotalAmount` | `string` | A formatted string representing the total amount donated (e.g., `"125.50 USDT"`). |
-| `supporters` | `DonateHistory` | An object containing supporter data, including the list of supporters, currency, and payment method details. |
-| `loading` | `boolean` | A boolean indicating if the supporter data is currently being fetched. |
-| `donateSettings` | `DonationSettings` | The processed donation settings object, including defaults inherited from `DonateProvider`. |
+```tsx Default Donation Button icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context';
+
+function App() {
+  const { session, connect } = useSessionContext();
+
+  if (!session) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="blog-post-123"
+        description="Donations for Blog Post 123"
+        defaultSettings={{
+          btnText: 'Buy me a coffee',
+          historyType: 'avatar',
+        }}>
+        <CheckoutDonate
+          settings={{
+            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...gCLd', // Author's DID address
+                share: '100',
+              },
+            ],
+          }}
+          onPaid={() => {
+            console.log('Donation successful!');
+          }}
+        />
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
 
-Here is an example of a custom donation UI:
+### Custom UI Mode
 
-```tsx
-import { CheckoutDonate, formatAmount } from '@blocklet/payment-react';
-import { Button, CircularProgress, Typography, List, ListItem, ListItemText } from '@mui/material';
+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.
 
-// Assuming PaymentProvider and DonateProvider are set up in a parent component.
+```tsx Custom Donation UI icon=logos:react
+import {
+  PaymentProvider,
+  DonateProvider,
+  CheckoutDonate,
+} from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session-context';
+import { CircularProgress, Button } from '@mui/material';
 
 function CustomDonationDisplay() {
+  const { session, connect } = 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',
+    beneficiaries: [
+      {
+        address: 'z2qa...gCLd', // Author's DID address
+        share: '100',
+      },
+    ],
+  };
+
   return (
-    <CheckoutDonate
-      mode="custom"
-      settings={{
-        target: "post-123",
-        title: "Support the Author",
-        description: "Your support is appreciated!",
-        reference: "https://your-site.com/posts/123",
-        beneficiaries: [{ address: "did:abt:z123...", share: "100" }],
-      }}
-    >
-      {(openDonate, totalAmount, supporters, loading) => (
-        <div>
-          <Typography variant="h5">Our Supporters</Typography>
-          <Button variant="contained" onClick={openDonate} sx={{ my: 2 }}>Support Us</Button>
-          {loading ? (
-            <CircularProgress />
-          ) : (
-            <div>
-              <Typography variant="subtitle1">Total Donations: {totalAmount}</Typography>
-              <List>
-                {supporters.supporters && supporters.supporters.map(supporter => (
-                  <ListItem key={supporter.id}>
-                    <ListItemText 
-                      primary={supporter.customer?.name} 
-                      secondary={`${formatAmount(supporter.amount_total, supporters.currency?.decimal)} ${supporters.currency?.symbol}`}
-                    />
-                  </ListItem>
-                ))}
-              </List>
+    <PaymentProvider session={session} connect={connect}>
+      <DonateProvider
+        mountLocation="blog-post-123"
+        description="Donations for Blog Post 123">
+        <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}>
+                {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>
+                  ))}
+                </ul>
+              )}
             </div>
           )}
-        </div>
-      )}
-    </CheckoutDonate>
+        </CheckoutDonate>
+      </DonateProvider>
+    </PaymentProvider>
   );
 }
 ```
-This custom setup gives you full control over the presentation of donation information.
-
-## Admin Features
 
-If the current user session has an `owner` or `admin` role, a settings icon will appear in the title of the donation dialog. Clicking this icon opens the donation configuration interface, allowing administrators to modify donation settings directly from the UI.
+The `children` function receives the following arguments:
 
-This feature requires that the `DonateProvider` is properly configured and that the underlying Payment Kit blocklet supports this functionality.
+-   `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.