@blocklet/payment-react 1.19.22 → 1.20.0

package/docs/components-business-overdue-invoice-payment.md

@@ -0,0 +1,231 @@
+# OverdueInvoicePayment
+
+The `OverdueInvoicePayment` component is designed to handle the payment of overdue invoices for a specific customer or subscription. It can operate in two modes: a default dialog mode that presents a pre-built UI for payment, or a custom mode that provides data and a payment handler to build a custom user interface.
+
+This component streamlines the process of collecting late payments by summarizing amounts by currency and initiating a batch payment process through the user's DID Wallet.
+
+## When to Use
+
+Use this component in your application's subscription management or customer billing sections to:
+
+- Prompt users to pay for a subscription that has fallen into a `past_due` status.
+- Allow customers to clear all outstanding invoices across multiple subscriptions in a single operation.
+
+## Component Logic Flow
+
+The component follows a clear sequence to manage overdue payments:
+
+```d2
+shape: sequence_diagram
+
+User: "User"
+App: "Your Application"
+OIP: "OverdueInvoicePayment"
+PaymentProvider: "PaymentProvider"
+API: "Payment Service API"
+
+User -> App: "Views page with overdue invoices"
+App -> OIP: "Renders with subscriptionId or customerId"
+OIP -> API: "GET /overdue/invoices"
+API -> OIP: "Returns summary & invoices list"
+
+alt "Invoices exist"
+  OIP -> App: "Renders payment UI (dialog/custom)"
+  User -> OIP: "Clicks 'Pay Now'"
+  OIP -> PaymentProvider: "Calls connect.open()"
+  PaymentProvider -> User: "Shows DID Wallet connect modal"
+  User -> PaymentProvider: "Scans & confirms payment"
+  PaymentProvider -> API: "Processes batch payment"
+  API -> PaymentProvider: "Payment successful"
+  PaymentProvider -> OIP: "Triggers onSuccess"
+  OIP -> OIP: "Refreshes invoice data"
+  OIP -> App: "Calls onPaid() & closes UI"
+else "No overdue invoices"
+  OIP -> App: "Displays success/empty message"
+end
+```
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `subscriptionId` | `string` | Optional. The ID of the subscription to check for overdue invoices. Either `subscriptionId` or `customerId` must be provided. |
+| `customerId` | `string` | Optional. The customer's ID (or DID) to check for all overdue invoices across their subscriptions. |
+| `mode` | `'default' \| 'custom'` | Optional. The rendering mode. `'default'` displays a pre-built dialog. `'custom'` uses a render prop for a custom UI. Defaults to `'default'`. |
+| `onPaid` | `(id, currencyId, type) => void` | Optional. A callback function executed after all overdue invoices are paid. It receives the source ID (`subscriptionId` or `customerId`), the currency ID, and the source type (`'subscription'` or `'customer'`). |
+| `dialogProps` | `object` | Optional. Props to pass to the underlying Material-UI `Dialog` component in `default` mode. Can be used to control its `open` state, `title`, and `onClose` behavior. |
+| `detailLinkOptions` | `object` | Optional. An object to configure the "view details" link in the default dialog. Shape: `{ enabled?: boolean, onClick?: (e) => void, title?: string }`. |
+| `successToast` | `boolean` | Optional. If `true`, a success toast notification is shown upon successful payment. Defaults to `true`. |
+| `alertMessage` | `string` | Optional. A custom message to append to the default alert text when checking by `customerId`. |
+| `children` | `function` | Optional. A render prop function used only when `mode="custom"`. It receives `handlePay` and `data` as arguments. |
+| `authToken` | `string` | Optional. An authentication token for API requests, useful for cross-origin scenarios where session cookies are not available. |
+
+## Usage
+
+> All examples assume you have set up `PaymentProvider` and a `useSessionContext` hook to provide session data. The `useSessionContext` hook is a local utility to access your application's session context. For a complete guide on this setup, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+
+### Default Mode Usage
+
+In its default mode, the component renders a dialog that summarizes the overdue payments and prompts the user to pay. This is the quickest way to implement overdue payment handling.
+
+#### Handling a Single Subscription's Overdue Invoices
+
+Provide the `subscriptionId` to target a specific subscription. A dialog will appear if there are any overdue invoices.
+
+```tsx
+import { PaymentProvider, OverdueInvoicePayment } from '@blocklet/payment-react';
+// This is a local utility to get session info from your app's context.
+// See the PaymentProvider docs for setup details.
+import { useSessionContext } from 'src/hooks/session';
+
+function SubscriptionDetailsPage({ subscriptionId }) {
+  const { session, connect: connectApi } = useSessionContext();
+
+  const handlePaymentSuccess = () => {
+    console.log('All overdue invoices for the subscription have been paid.');
+    // You can refresh the subscription status here
+  };
+
+  if (!session || !connectApi) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <OverdueInvoicePayment
+        subscriptionId={subscriptionId}
+        onPaid={handlePaymentSuccess}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+#### Handling All of a Customer's Overdue Invoices
+
+Provide the `customerId` (which can be the user's DID) to consolidate all overdue invoices from all of their subscriptions into a single payment flow.
+
+```tsx
+import { PaymentProvider, OverdueInvoicePayment } from '@blocklet/payment-react';
+// This is a local utility to get session info from your app's context.
+// See the PaymentProvider docs for setup details.
+import { useSessionContext } from 'src/hooks/session';
+
+function CustomerDashboard() {
+  const { session, connect: connectApi } = useSessionContext();
+
+  if (!session?.user?.did || !connectApi) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <OverdueInvoicePayment
+        customerId={session.user.did}
+        onPaid={() => {
+          console.log("All of the customer's overdue invoices are paid.");
+          // Refresh customer data or redirect
+        }}
+        dialogProps={{
+          title: 'Outstanding Payments',
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+### Custom Mode Usage
+
+For full control over the user interface, set `mode="custom"`. This allows you to build a completely custom component for handling overdue payments using the `children` render prop.
+
+The render prop receives two arguments:
+1.  `handlePay`: A function to trigger the payment process. It takes a `SummaryItem` object as an argument.
+2.  `data`: An object containing all the necessary information about the overdue invoices.
+
+#### Building a Custom UI
+
+Here is an example of creating a custom card to display overdue payment information and trigger payments.
+
+```tsx
+import {
+  PaymentProvider,
+  OverdueInvoicePayment,
+  Amount,
+} from '@blocklet/payment-react';
+import { Card, CardContent, Typography, Button, Stack } from '@mui/material';
+// This is a local utility to get session info from your app's context.
+// See the PaymentProvider docs for setup details.
+import { useSessionContext } from 'src/hooks/session';
+
+function CustomOverdueUI({ subscriptionId }) {
+  const { session, connect: connectApi } = useSessionContext();
+
+  if (!session || !connectApi) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <OverdueInvoicePayment
+        subscriptionId={subscriptionId}
+        mode="custom"
+        onPaid={() => console.log('Paid!')}>
+        {(handlePay, { summary, invoices, subscription }) => {
+          if (!invoices || invoices.length === 0) {
+            return <Typography>No overdue payments. All good!</Typography>;
+          }
+
+          return (
+            <Card variant="outlined">
+              <CardContent>
+                <Typography variant="h6" gutterBottom>
+                  Action Required for {subscription?.description}
+                </Typography>
+                <Typography color="error" gutterBottom>
+                  You have {invoices.length} overdue invoice(s).
+                </Typography>
+                <Stack spacing={2} sx={{ mt: 2 }}>
+                  {Object.values(summary).map((info) => (
+                    <Stack
+                      key={info.currency.id}
+                      direction="row"
+                      justifyContent="space-between"
+                      alignItems="center">
+                      <Typography>
+                        Total Due: <Amount amount={info.amount} decimal={info.currency.decimal} symbol={info.currency.symbol} />
+                      </Typography>
+                      <Button
+                        onClick={() => handlePay(info)}
+                        variant="contained"
+                        color="primary">
+                        Pay Now
+                      </Button>
+                    </Stack>
+                  ))}
+                </Stack>
+              </CardContent>
+            </Card>
+          );
+        }}
+      </OverdueInvoicePayment>
+    </PaymentProvider>
+  );
+}
+```
+
+#### Custom Mode `data` Object
+
+The `data` object passed to the `children` render prop contains the following fields:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `subscription` | `Subscription` | The full subscription object, if `subscriptionId` was provided. |
+| `summary` | `{ [key: string]: SummaryItem }` | An object summarizing the total amount due, grouped by currency ID. Each `SummaryItem` contains `amount`, `currency`, and `method`. |
+| `invoices` | `Invoice[]` | An array of the raw overdue invoice objects. |
+| `subscriptionCount` | `number` | The number of subscriptions with overdue payments, if `customerId` was provided. |
+| `detailUrl` | `string` | A pre-generated URL to the detailed invoice or subscription page. |
+
+### Note on Payment Methods
+
+The batch payment flow initiated by this component currently supports wallet-based payments (like ArcBlock, Ethereum). It does not support batch payments via Stripe. If an overdue invoice's payment method is Stripe, the component will guide the user to a page where they can pay manually.

package/docs/components-business-resume-subscription.md

@@ -0,0 +1,177 @@
+# ResumeSubscription
+
+The `ResumeSubscription` component provides a user interface for resuming a canceled subscription. It handles the necessary logic, including prompting the user to re-stake funds if required, and appears as a modal dialog by default.
+
+This component must be used within a [`PaymentProvider`](./providers-payment-provider.md) to access the required payment context.
+
+## How It Works
+
+The component streamlines the subscription recovery process. When rendered, it first checks if the subscription requires a new stake to be resumed. Based on this information, it presents one of two flows:
+
+1.  **Direct Resume**: If no new stake is needed, the user can confirm to directly reactivate the subscription.
+2.  **Resume with Re-Stake**: If a stake is required, the component will initiate a wallet connection flow, asking the user to approve the staking transaction to resume their subscription.
+
+```d2
+shape: sequence_diagram
+
+User
+"React App"
+"ResumeSubscription"
+"Payment API"
+"DID Wallet"
+
+User -> "React App": "Clicks 'Resume Subscription'"
+"React App" -> "ResumeSubscription": "Renders with subscriptionId"
+
+"ResumeSubscription" -> "Payment API": "GET /recover-info"
+"Payment API" --> "ResumeSubscription": "{ needStake }"
+
+alt "Direct Resume (needStake is false)" {
+  "ResumeSubscription" -> "Payment API": "PUT /recover"
+  "Payment API" --> "ResumeSubscription": "{ subscription }"
+}
+
+alt "Re-Stake Required (needStake is true)" {
+  "ResumeSubscription" -> "DID Wallet": "Opens connect for 're-stake'"
+  User -> "DID Wallet": "Approves transaction"
+  "DID Wallet" --> "ResumeSubscription": "onSuccess()"
+}
+
+"ResumeSubscription" -> "Payment API": "GET /subscriptions/:id (on success)"
+"Payment API" --> "ResumeSubscription": "Updated subscription data"
+"ResumeSubscription" -> "React App": "onResumed(subscription)"
+"React App" -> User: "UI is updated"
+```
+
+## Props
+
+| Prop             | Type                                                     | Description                                                                                                                                                                                                                                                            |
+| :--------------- | :------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subscriptionId` | `string`                                                 | **Required.** The ID of the subscription to be resumed.                                                                                                                                                                                                                |
+| `onResumed`      | `(sub: Subscription \| TSubscriptionExpanded) => void` | Optional. A callback function that is executed after the subscription has been successfully resumed. It receives the updated subscription object as an argument.                                                                                                        |
+| `dialogProps`    | `object`                                                 | Optional. Props to customize the underlying Material-UI Dialog component. Default: `{ open: true }`. Key properties include:<br />- `open`: `boolean`, controls visibility.<br />- `onClose`: `() => void`, a callback for when the dialog is closed.<br />- `title`: `string`, overrides the default dialog title. | 
+| `successToast`   | `boolean`                                                | Optional. If `true`, a success toast notification is shown upon successful resumption. Defaults to `true`.                                                                                                                                                                  |
+| `authToken`      | `string`                                                 | Optional. An authentication token to be included in API requests. This is useful for cross-origin requests or when the application manages authentication separately.                                                                                                |
+
+## Usage Examples
+
+<div class="lead">All examples require the component to be wrapped in a `PaymentProvider`. The `session` and `connect` props are obtained using a custom `useSessionContext` hook, which represents your application's authentication state. For detailed setup instructions, please refer to the <a href="/providers/payment-provider">PaymentProvider documentation</a>.</div>
+
+### Basic Usage
+
+This example shows the simplest way to use `ResumeSubscription`. The dialog will be open by default, and a success toast will appear upon completion.
+
+```tsx
+import React from 'react';
+import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';
+
+// Placeholder for your application's session context hook.
+// See the PaymentProvider documentation for setup details.
+import { useSessionContext } from '../hooks/use-session-context';
+
+function SubscriptionManagementPage({ subscriptionId, refetchSubscription }) {
+  // session and connect are derived from your application's auth service.
+  const { session, connect } = useSessionContext();
+
+  if (!session) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <ResumeSubscription
+        subscriptionId={subscriptionId}
+        onResumed={(subscription) => {
+          console.log('Subscription resumed:', subscription);
+          // Update your application's state here.
+          refetchSubscription();
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+### Controlling the Dialog
+
+You can manage the dialog's visibility from a parent component by passing its state down through `dialogProps`.
+
+```tsx
+import React, { useState } from 'react';
+import { Button } from '@mui/material';
+import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';
+
+// Placeholder for your application's session context hook.
+// See the PaymentProvider documentation for setup details.
+import { useSessionContext } from '../hooks/use-session-context';
+
+function SubscriptionDetails({ subscriptionId, refetchSubscription }) {
+  const [isResumeDialogOpen, setResumeDialogOpen] = useState(false);
+  const { session, connect } = useSessionContext();
+
+  const handleCloseDialog = () => {
+    setResumeDialogOpen(false);
+  };
+
+  if (!session) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <Button onClick={() => setResumeDialogOpen(true)}>
+        Resume Subscription
+      </Button>
+
+      {isResumeDialogOpen && (
+        <ResumeSubscription
+          subscriptionId={subscriptionId}
+          onResumed={() => {
+            console.log('Subscription has been resumed.');
+            handleCloseDialog();
+            refetchSubscription(); // Refresh subscription data in parent component.
+          }}
+          dialogProps={{
+            open: isResumeDialogOpen,
+            onClose: handleCloseDialog,
+            title: 'Confirm Subscription Renewal',
+          }}
+        />
+      )}
+    </PaymentProvider>
+  );
+}
+```
+
+### Usage with an Authentication Token
+
+If your API requests require an authentication token, provide it using the `authToken` prop. This is useful for secure communication between different services or Blocklets.
+
+```tsx
+import React from 'react';
+import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';
+
+// Placeholder for your application's session context hook.
+// See the PaymentProvider documentation for setup details.
+import { useSessionContext } from '../hooks/use-session-context';
+
+function SecureSubscriptionResume({ subscriptionId, token }) {
+  const { session, connect } = useSessionContext();
+
+  if (!session) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connect}>
+      <ResumeSubscription
+        subscriptionId={subscriptionId}
+        authToken={token}
+        onResumed={(subscription) => {
+          console.log('Subscription resumed securely:', subscription.id);
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+```

package/docs/components-business.md

@@ -0,0 +1,45 @@
+# Business Logic Components
+
+Business logic components are specialized React components designed to handle complex, high-level user flows related to subscription and invoice management. These components encapsulate API calls, state management, and user interactions for common scenarios, allowing you to integrate sophisticated features with minimal effort.
+
+These components are ready to be integrated into your application to address specific business needs, such as recovering revenue from failed payments or improving user retention.
+
+```d2
+direction: down
+
+"User Application": {
+  shape: cloud
+}
+
+"Business Logic Components": {
+  shape: package
+  "OverdueInvoicePayment"
+  "ResumeSubscription"
+  "Auto-Topup Components"
+}
+
+"Payment Service API": {
+  shape: database
+}
+
+"User Application" -> "Business Logic Components": "Integrates"
+"Business Logic Components.OverdueInvoicePayment" -> "Payment Service API": "Pays for overdue invoices"
+"Business Logic Components.ResumeSubscription" -> "Payment Service API": "Reactivates subscription"
+"Business Logic Components.Auto-Topup Components" -> "Payment Service API": "Configures auto-recharge"
+```
+
+This section provides an overview of the available business logic components. For detailed API references and usage examples, select a component below.
+
+<x-cards data-columns="3">
+  <x-card data-title="OverdueInvoicePayment" data-icon="lucide:alert-circle" data-href="/components/business/overdue-invoice-payment">
+    A component that provides a complete UI flow for handling overdue invoices for a subscription or an entire customer account.
+  </x-card>
+  <x-card data-title="ResumeSubscription" data-icon="lucide:refresh-cw" data-href="/components/business/resume-subscription">
+    A component that facilitates resuming a previously canceled subscription, including handling complex scenarios like re-staking.
+  </x-card>
+  <x-card data-title="Auto-Topup Components" data-icon="lucide:battery-charging" data-href="/components/business/auto-topup">
+    A set of components for managing automatic credit top-ups when a user's balance falls below a configured threshold.
+  </x-card>
+</x-cards>
+
+After handling these business-specific tasks, you may want to display the results to the user. Proceed to the [History Components](./components-history.md) section to learn how to display lists of invoices, payments, and credit transactions.

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

@@ -0,0 +1,199 @@
+# 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.
+
+To function correctly, `CheckoutDonate` must be wrapped within both a [`PaymentProvider`](./providers-payment-provider.md) and a [`DonateProvider`](./providers-donate-provider.md).
+
+## Props
+
+| 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. |
+
+### `CheckoutDonateSettings`
+
+This object configures the donation's behavior and appearance.
+
+| 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 
+} from '@blocklet/payment-react';
+
+// 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 DonationSection() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <DonateProvider 
+        mountLocation="unique-page-identifier"
+        description="Donations for this page"
+      >
+        <CheckoutDonate
+          settings={{
+            target: "post-123", // Unique ID for this donation target
+            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",
+            beneficiaries: [
+              {
+                address: "did:abt:z123...", // Beneficiary's DID address
+                share: "100",
+              },
+            ],
+          }}
+          onPaid={(session) => console.log('Donation successful:', session.id)}
+        />
+      </DonateProvider>
+    </PaymentProvider>
+  );
+}
+```
+
+## Usage Modes
+
+The `CheckoutDonate` component can be rendered in three different modes, controlled by the `mode` prop.
+
+### Default Mode
+
+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'
+      },
+    },
+  }}
+/>
+```
+
+### 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',
+    }
+  }}
+/>
+```
+
+### Custom Mode
+
+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.
+
+The `children` function receives the following arguments:
+
+| 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`. |
+
+Here is an example of a custom donation UI:
+
+```tsx
+import { CheckoutDonate, formatAmount } from '@blocklet/payment-react';
+import { Button, CircularProgress, Typography, List, ListItem, ListItemText } from '@mui/material';
+
+// Assuming PaymentProvider and DonateProvider are set up in a parent component.
+
+function CustomDonationDisplay() {
+  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>
+            </div>
+          )}
+        </div>
+      )}
+    </CheckoutDonate>
+  );
+}
+```
+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.
+
+This feature requires that the `DonateProvider` is properly configured and that the underlying Payment Kit blocklet supports this functionality.