@blocklet/payment-react 1.23.0 → 1.23.1

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

@@ -2,92 +2,90 @@
 
 The `OverdueInvoicePayment` component is a specialized tool designed to handle the payment of overdue invoices for a specific customer or subscription. It simplifies the process by automatically fetching overdue invoices and presenting users with a clear interface to settle their outstanding payments.
 
-This component can operate in two modes: a default mode that displays a pre-built dialog for quick integration, and a custom mode that provides the flexibility to build a unique user interface using a render prop.
-
-## How It Works
-
-The component orchestrates the entire overdue payment process, from fetching data to handling the final transaction confirmation.
-
-```d2 Overdue Payment Flow
-direction: down
-
-User: { 
-  shape: c4-person 
-}
-
-Client-App: {
-  label: "Client Application"
-  shape: rectangle
-
-  OverdueInvoicePayment-Component: {
-    label: "OverdueInvoicePayment Component"
-    shape: rectangle
-  }
-}
-
-Payment-Backend: {
-  label: "Payment Backend"
-  shape: cylinder
-}
-
-DID-Wallet: {
-  label: "DID Wallet"
-  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
-}
-
-User -> Client-App.OverdueInvoicePayment-Component: "1. Renders the component"
-Client-App.OverdueInvoicePayment-Component -> Payment-Backend: "2. Fetch overdue invoices"
-Payment-Backend -> Client-App.OverdueInvoicePayment-Component: "3. Return invoice summary"
-Client-App.OverdueInvoicePayment-Component -> User: "4. Display payment dialog"
-User -> Client-App.OverdueInvoicePayment-Component: "5. Clicks 'Pay Now'"
-Client-App.OverdueInvoicePayment-Component -> DID-Wallet: "6. Opens connect session (collect-batch)"
-User -> DID-Wallet: "7. Approves payment"
-DID-Wallet -> Client-App.OverdueInvoicePayment-Component: "8. Sends success callback"
-Payment-Backend -> Client-App.OverdueInvoicePayment-Component: "9. WebSocket event (invoice.paid)"
-Client-App.OverdueInvoicePayment-Component -> User: "10. Update UI (e.g., close dialog)"
-
-```
+This component can operate in two modes: a default mode that displays a pre-built dialog for quick integration, and a custom mode that provides the flexibility to build a unique user interface using a render prop. It must be wrapped within a `PaymentProvider` to function correctly.
 
 ## Props
 
 The `OverdueInvoicePayment` component accepts the following props to customize its behavior:
 
-| Prop | Type | Description |
-|---|---|---|
-| `subscriptionId` | `string` | The ID of the subscription to check for overdue invoices. Either `subscriptionId` or `customerId` must be provided. |
-| `customerId` | `string` | The ID or DID of the customer. Use this to handle all overdue invoices for a customer. |
-| `mode` | `'default'` \| `'custom'` | The rendering mode. `'default'` shows a pre-built dialog. `'custom'` uses the `children` render prop for a custom UI. Defaults to `'default'`. |
-| `onPaid` | `(id, currencyId, type) => void` | An optional callback function that is triggered after payment is successfully completed. `id` will be the `subscriptionId` or `customerId`, `type` will be `'subscription'` or `'customer'`. |
-| `dialogProps` | `object` | Optional props to pass to the underlying Material-UI `Dialog` component in `default` mode. e.g., `{ open: true, title: 'Custom Title', onClose: handleClose }`. |
-| `detailLinkOptions` | `object` | Optional settings for the "View Details" link. Can be used to disable the link, change its text, or provide a custom `onClick` handler. Format: `{ enabled?: boolean, onClick?: function, title?: string }`. |
-| `successToast` | `boolean` | If `true`, a success toast notification is shown upon successful payment. Defaults to `true`. |
-| `alertMessage` | `string` | An optional message to append to the default title text when in customer mode. |
-| `children` | `(handlePay, data) => React.ReactNode` | A render prop function used only when `mode` is `'custom'`. It receives a `handlePay` function and a `data` object. |
-| `authToken` | `string` | An optional authentication token for API requests, useful for server-to-server or cross-origin scenarios. |
-
-### `children` Render Prop
-
-When using `mode="custom"`, the `children` function receives two arguments:
-
-1.  **`handlePay(item: SummaryItem)`**: A function to initiate the payment process for a specific currency group. The `item` object comes from the `data.summary` object.
-2.  **`data`**: An object containing the fetched payment information:
-    *   `subscription?: Subscription`: The subscription details, if `subscriptionId` was provided.
-    *   `summary: { [key: string]: SummaryItem }`: An object where each key is a currency ID and the value contains the total amount, currency details, and payment method.
-    *   `invoices: Invoice[]`: An array of all overdue invoice objects.
-    *   `subscriptionCount?: number`: The number of subscriptions with overdue invoices (for customer mode).
-    *   `detailUrl: string`: The URL to view detailed invoice information.
+<x-field-group>
+  <x-field data-name="subscriptionId" data-type="string" data-required="false">
+    <x-field-desc markdown>The ID of the subscription to check for overdue invoices. Either `subscriptionId` or `customerId` must be provided.</x-field-desc>
+  </x-field>
+  <x-field data-name="customerId" data-type="string" data-required="false">
+    <x-field-desc markdown>The ID or DID of the customer. Use this to handle all overdue invoices for a specific customer.</x-field-desc>
+  </x-field>
+  <x-field data-name="mode" data-type="'default' | 'custom'" data-default="default" data-required="false">
+    <x-field-desc markdown>The rendering mode. `'default'` shows a pre-built dialog. `'custom'` uses the `children` render prop for a custom UI.</x-field-desc>
+  </x-field>
+  <x-field data-name="onPaid" data-type="function" data-required="false">
+    <x-field-desc markdown>An optional callback function that is triggered after payment for a specific currency is successfully completed. It receives `(id, currencyId, type)`, where `id` is the `subscriptionId` or `customerId`, and `type` is `'subscription'` or `'customer'`.</x-field-desc>
+    <x-field data-name="parameters" data-type="object">
+      <x-field data-name="id" data-type="string" data-desc="The subscriptionId or customerId."></x-field>
+      <x-field data-name="currencyId" data-type="string" data-desc="The ID of the currency used for payment."></x-field>
+      <x-field data-name="type" data-type="'subscription' | 'customer'" data-desc="Indicates if the payment was for a subscription or a customer."></x-field>
+    </x-field>
+  </x-field>
+  <x-field data-name="dialogProps" data-type="object" data-required="false">
+    <x-field-desc markdown>Optional props to pass to the underlying Material-UI `Dialog` component in `default` mode. For example, `{ open: true, title: 'Custom Title', onClose: handleClose }`.</x-field-desc>
+  </x-field>
+  <x-field data-name="detailLinkOptions" data-type="object" data-required="false">
+    <x-field-desc markdown>Optional settings for the "View Details" link. Can be used to disable the link, change its text, or provide a custom `onClick` handler.</x-field-desc>
+    <x-field data-name="enabled" data-type="boolean" data-required="false" data-desc="Whether the link is enabled."></x-field>
+    <x-field data-name="onClick" data-type="(e: React.MouseEvent) => void" data-required="false" data-desc="Custom click handler."></x-field>
+    <x-field data-name="title" data-type="string" data-required="false" data-desc="Custom link text."></x-field>
+  </x-field>
+  <x-field data-name="successToast" data-type="boolean" data-default="true" data-required="false">
+    <x-field-desc markdown>If `true`, a success toast notification is shown upon successful payment.</x-field-desc>
+  </x-field>
+  <x-field data-name="alertMessage" data-type="string" data-required="false">
+    <x-field-desc markdown>An optional message to append to the default title text when in customer mode.</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 `'custom'`. It receives a `handlePay` function and a `data` object.</x-field-desc>
+    <x-field data-name="parameters" data-type="object">
+      <x-field data-name="handlePay" data-type="(item: SummaryItem) => void" data-desc="Function to initiate the payment process for a specific currency group."></x-field>
+      <x-field data-name="data" data-type="object" data-desc="An object containing the fetched payment information."></x-field>
+    </x-field>
+  </x-field>
+  <x-field data-name="authToken" data-type="string" data-required="false">
+    <x-field-desc markdown>An optional authentication token for API requests, useful for server-to-server or cross-origin scenarios.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### `children` Render Prop Data
+
+When using `mode="custom"`, the `data` object passed to the `children` function contains the following fields:
+
+<x-field-group>
+  <x-field data-name="subscription" data-type="Subscription" data-required="false">
+    <x-field-desc markdown>The subscription details, if `subscriptionId` was provided.</x-field-desc>
+  </x-field>
+  <x-field data-name="summary" data-type="{ [key: string]: SummaryItem }" data-required="true">
+    <x-field-desc markdown>An object where each key is a currency ID. The value contains the total amount, currency details, and payment method for that currency.</x-field-desc>
+  </x-field>
+  <x-field data-name="invoices" data-type="Invoice[]" data-required="true">
+    <x-field-desc markdown>An array of all overdue invoice objects.</x-field-desc>
+  </x-field>
+  <x-field data-name="subscriptionCount" data-type="number" data-required="false">
+    <x-field-desc markdown>The number of subscriptions with overdue invoices (for customer mode).</x-field-desc>
+  </x-field>
+  <x-field data-name="detailUrl" data-type="string" data-required="true">
+    <x-field-desc markdown>The URL to view detailed invoice information.</x-field-desc>
+  </x-field>
+</x-field-group>
 
 ## Usage Examples
 
-All examples assume you have `PaymentProvider` set up in your application.
+All examples assume you have `PaymentProvider` set up in your application as detailed in the [PaymentProvider documentation](./providers-payment-provider.md).
 
 ### 1. Default Mode for a Subscription
 
 This is the simplest way to handle overdue payments for a specific subscription. The component will automatically render a dialog if any overdue invoices are found.
 
-```tsx SubscriptionOverdue.tsx icon=logos:react
+```javascript SubscriptionOverdue.jsx icon=logos:react
 import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react';
-import { useSessionContext } from './hooks/session'; // Your custom session hook
+import { useSessionContext } from '../hooks/session'; // Your custom session hook
 
 function SubscriptionPage({ subscriptionId }) {
   const { session, connect } = useSessionContext();
@@ -100,10 +98,7 @@ function SubscriptionPage({ subscriptionId }) {
   return (
     <PaymentProvider session={session} connect={connect}>
       {/* This component will be null if there are no overdue invoices */}
-      <OverdueInvoicePayment
-        subscriptionId={subscriptionId}
-        onPaid={handlePaymentSuccess}
-      />
+      <OverdueInvoicePayment subscriptionId={subscriptionId} onPaid={handlePaymentSuccess} />
       {/* Other subscription details can be rendered here */}
     </PaymentProvider>
   );
@@ -114,9 +109,9 @@ function SubscriptionPage({ subscriptionId }) {
 
 Use this to create a centralized place for a customer to pay all their overdue invoices across multiple subscriptions.
 
-```tsx CustomerDashboard.tsx icon=logos:react
+```javascript CustomerDashboard.jsx icon=logos:react
 import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react';
-import { useSessionContext } from './hooks/session'; // Your custom session hook
+import { useSessionContext } from '../hooks/session'; // Your custom session hook
 
 function CustomerDashboard() {
   const { session, connect } = useSessionContext();
@@ -142,21 +137,30 @@ function CustomerDashboard() {
 
 For full control over the user experience, use `mode="custom"`. This allows you to integrate the payment functionality directly into your existing UI instead of using a dialog.
 
-```tsx CustomOverdueUI.tsx icon=logos:react
-import { OverdueInvoicePayment, PaymentProvider, Amount } from '@blocklet/payment-react';
-import { useSessionContext } from './hooks/session'; // Your custom session hook
+```javascript CustomOverdueUI.jsx icon=logos:react
+import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from '../hooks/session'; // Your custom session hook
 import { Card, CardContent, Typography, Button, Stack } from '@mui/material';
 
 function CustomOverdueUI({ subscriptionId }) {
   const { session, connect } = useSessionContext();
 
+  // A simple Amount component for formatting
+  const Amount = ({ amount, decimal, symbol }) => {
+    const formattedAmount = (parseInt(amount, 10) / 10 ** (decimal || 0)).toFixed(2);
+    return (
+      <strong>
+        {formattedAmount} {symbol}
+      </strong>
+    );
+  };
+
   return (
     <PaymentProvider session={session} connect={connect}>
       <OverdueInvoicePayment
         subscriptionId={subscriptionId}
         mode="custom"
-        onPaid={() => console.log('Custom UI payment successful!')}
-      >
+        onPaid={() => console.log('Custom UI payment successful!')}>
         {(handlePay, { summary, invoices }) => {
           const summaryList = Object.values(summary);
           if (invoices.length === 0) {
@@ -170,16 +174,17 @@ function CustomOverdueUI({ subscriptionId }) {
                   You have {invoices.length} overdue invoice(s).
                 </Typography>
                 <Stack spacing={2} mt={2}>
-                  {summaryList.map((item) => (
+                  {summaryList.map(item => (
                     <Stack key={item.currency.id} direction="row" justifyContent="space-between" alignItems="center">
                       <Typography>
-                        Total Due: <Amount amount={item.amount} decimal={item.currency.decimal} symbol={item.currency.symbol} />
+                        Total Due:{' '}
+                        <Amount
+                          amount={item.amount}
+                          decimal={item.currency.decimal}
+                          symbol={item.currency.symbol}
+                        />
                       </Typography>
-                      <Button
-                        variant="contained"
-                        color="primary"
-                        onClick={() => handlePay(item)}
-                      >
+                      <Button variant="contained" color="primary" onClick={() => handlePay(item)}>
                         Pay with {item.currency.symbol}
                       </Button>
                     </Stack>
@@ -194,3 +199,7 @@ function CustomOverdueUI({ subscriptionId }) {
   );
 }
 ```
+
+<!-- DIAGRAM_IMAGE_START:flowchart:4:3:1765377372 -->
+![OverdueInvoicePayment](assets/diagram/components-business-overdue-invoice-payment-01.jpg)
+<!-- DIAGRAM_IMAGE_END -->

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

@@ -8,46 +8,9 @@
 
 該元件協調整個逾期付款流程，從擷取資料到處理最終的交易確認。
 
-```d2 逾期支付流程
-direction: down
-
-User: { 
-  label: "使用者"
-  shape: c4-person 
-}
-
-Client-App: {
-  label: "客戶端應用程式"
-  shape: rectangle
-
-  OverdueInvoicePayment-Component: {
-    label: "OverdueInvoicePayment 元件"
-    shape: rectangle
-  }
-}
-
-Payment-Backend: {
-  label: "支付後端"
-  shape: cylinder
-}
-
-DID-Wallet: {
-  label: "DID 錢包"
-  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
-}
-
-User -> Client-App.OverdueInvoicePayment-Component: "1. 渲染元件"
-Client-App.OverdueInvoicePayment-Component -> Payment-Backend: "2. 擷取逾期發票"
-Payment-Backend -> Client-App.OverdueInvoicePayment-Component: "3. 回傳發票摘要"
-Client-App.OverdueInvoicePayment-Component -> User: "4. 顯示支付對話方塊"
-User -> Client-App.OverdueInvoicePayment-Component: "5. 點擊「立即支付」"
-Client-App.OverdueInvoicePayment-Component -> DID-Wallet: "6. 開啟連接會話 (collect-batch)"
-User -> DID-Wallet: "7. 批准支付"
-DID-Wallet -> Client-App.OverdueInvoicePayment-Component: "8. 發送成功回呼"
-Payment-Backend -> Client-App.OverdueInvoicePayment-Component: "9. WebSocket 事件 (invoice.paid)"
-Client-App.OverdueInvoicePayment-Component -> User: "10. 更新 UI (例如，關閉對話方塊)"
-
-```
+<!-- DIAGRAM_IMAGE_START:flowchart:4:3::1765377372 -->
+![OverdueInvoicePayment](assets/diagram/components-business-overdue-invoice-payment-01.zh-TW.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
 ## Props
 

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

@@ -8,46 +8,9 @@
 
 该组件协调整个逾期支付过程，从获取数据到处理最终的交易确认。
 
-```d2 Overdue Payment Flow
-direction: down
-
-User: { 
-  shape: c4-person
-  label: "用户"
-}
-
-Client-App: {
-  label: "客户端应用"
-  shape: rectangle
-
-  OverdueInvoicePayment-Component: {
-    label: "OverdueInvoicePayment 组件"
-    shape: rectangle
-  }
-}
-
-Payment-Backend: {
-  label: "支付后端"
-  shape: cylinder
-}
-
-DID-Wallet: {
-  label: "DID 钱包"
-  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
-}
-
-User -> Client-App.OverdueInvoicePayment-Component: "1. 渲染组件"
-Client-App.OverdueInvoicePayment-Component -> Payment-Backend: "2. 获取逾期发票"
-Payment-Backend -> Client-App.OverdueInvoicePayment-Component: "3. 返回发票摘要"
-Client-App.OverdueInvoicePayment-Component -> User: "4. 显示支付对话框"
-User -> Client-App.OverdueInvoicePayment-Component: "5. 点击“立即支付”"
-Client-App.OverdueInvoicePayment-Component -> DID-Wallet: "6. 打开连接会话 (collect-batch)"
-User -> DID-Wallet: "7. 批准支付"
-DID-Wallet -> Client-App.OverdueInvoicePayment-Component: "8. 发送成功回调"
-Payment-Backend -> Client-App.OverdueInvoicePayment-Component: "9. WebSocket 事件 (invoice.paid)"
-Client-App.OverdueInvoicePayment-Component -> User: "10. 更新 UI (例如，关闭对话框)"
-
-```
+<!-- DIAGRAM_IMAGE_START:flowchart:4:3::1765377372 -->
+![OverdueInvoicePayment](assets/diagram/components-business-overdue-invoice-payment-01.zh.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
 ## 属性
 

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

@@ -8,8 +8,8 @@
 
 以下の図は、ユーザーがサブスクリプションを再開する際のプロセスフローを示したもので、再ステーキングの条件分岐ロジックも含まれています。
 
-<!-- DIAGRAM_IMAGE_START:sequence:4:3 -->
-![ResumeSubscription](assets/diagram/resume-subscription-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:sequence:4:3:1764919317 -->
+![ResumeSubscription](assets/diagram/resume-subscription-diagram-0.ja.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 

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

@@ -8,7 +8,7 @@ This component must be used within a `PaymentProvider` to access the necessary c
 
 The following diagram illustrates the process flow when a user resumes a subscription, including the conditional logic for re-staking.
 
-<!-- DIAGRAM_IMAGE_START:sequence:4:3 -->
+<!-- DIAGRAM_IMAGE_START:sequence:4:3:1764919317 -->
 ![ResumeSubscription](assets/diagram/resume-subscription-diagram-0.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 

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

@@ -8,8 +8,8 @@
 
 下圖說明了使用者恢復訂閱時的流程，包括重新質押的條件邏輯。
 
-<!-- DIAGRAM_IMAGE_START:sequence:4:3 -->
-![ResumeSubscription](assets/diagram/resume-subscription-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:sequence:4:3::1764919317 -->
+![ResumeSubscription](assets/diagram/resume-subscription-diagram-0.zh-TW.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 

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

@@ -8,8 +8,8 @@
 
 下图说明了用户恢复订阅时的流程，包括重新质押的条件逻辑。
 
-<!-- DIAGRAM_IMAGE_START:sequence:4:3 -->
-![ResumeSubscription](assets/diagram/resume-subscription-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:sequence:4:3:1764919317 -->
+![ResumeSubscription](assets/diagram/resume-subscription-diagram-0.zh.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 

package/docs/components-checkout-checkout-donate.ja.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
-}
-
-# Initial Load
-app.checkout-donate -> payment-api: "設定と支援者を取得"
-
-# Donation Flow
-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.ja.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
 1.  **初期化**：`DonateProvider`は、一意の`mountLocation`によって識別されるバックエンドから、寄付設定（プリセット金額、ボタンテキストなど）を取得してキャッシュします。
 2.  **レンダリング**：`CheckoutDonate`は、取得した設定と自身のpropsに基づいて、ボタンまたはカスタムUIをレンダリングします。