@blocklet/payment-react 1.23.0 → 1.23.2

package/docs/components-checkout.md

@@ -1,65 +1,27 @@
 # Checkout Components
 
-The `@blocklet/payment-react` library provides a set of high-level Checkout Components designed to serve as complete, ready-to-use entry points for various payment scenarios. These components encapsulate the entire user flow, from selecting a product to completing the payment, allowing you to integrate complex payment experiences with minimal setup.
+This section covers the high-level components that serve as entry points for various checkout flows. These components are designed to provide a complete, out-of-the-box experience for common payment scenarios like standard payments from a link, selecting a plan from a pricing table, or making a donation. They encapsulate the necessary logic to initiate and process payments, often leveraging the core `CheckoutForm` component internally.
 
-Whether you need to display a pricing table, accept donations, or process a direct payment link, these components handle the underlying logic of session creation, state management, and UI rendering.
+### Component Relationship
 
-### Component Flow
+The typical flow involves a user interacting with an entry-point component like `CheckoutTable` or `CheckoutDonate`. These components handle the initial user interaction (e.g., selecting a subscription plan) and then create a `CheckoutSession`. Once the session is ready, they delegate the final payment processing to the `CheckoutForm`, which renders the actual payment interface.
 
-The typical flow involves a user interacting with an entry-point component like `CheckoutTable` or `CheckoutDonate`. These components then create a `CheckoutSession` and delegate the final payment processing to the core `CheckoutForm` component.
+The following diagram illustrates this component relationship:
 
-```d2 Checkout Component Flow icon=mdi:transit-connection-variant
-direction: down
+DIAGRAM_PLACEHOLDER
 
-User: {
-  shape: c4-person
-}
+This modular design allows for both flexibility and ease of use. You can quickly implement a complete payment workflow with a single component or compose them for more complex scenarios.
 
-Checkout-Flow: {
-  label: "Checkout Flow"
-
-  Entry-Points: {
-    label: "User-Facing Components"
-    shape: rectangle
-
-    CheckoutTable: {
-      label: "CheckoutTable"
-    }
-
-    CheckoutDonate: {
-      label: "CheckoutDonate"
-    }
-  }
-
-  Core-Processor: {
-    label: "Core Payment Processor"
-    shape: rectangle
-
-    CheckoutForm: {
-      label: "CheckoutForm"
-    }
-  }
-}
-
-User -> Checkout-Flow.Entry-Points.CheckoutTable: "Selects a subscription"
-User -> Checkout-Flow.Entry-Points.CheckoutDonate: "Makes a donation"
-Checkout-Flow.Entry-Points.CheckoutTable -> Checkout-Flow.Core-Processor.CheckoutForm: "On plan selection"
-Checkout-Flow.Entry-Points.CheckoutDonate -> Checkout-Flow.Core-Processor.CheckoutForm: "On donate action"
-Checkout-Flow.Core-Processor.CheckoutForm -> User: "Payment Result"
-```
-
-Explore the components below to find the best fit for your application's needs.
+For more detailed information on each component, including props and usage examples, please refer to their respective documentation pages.
 
 <x-cards data-columns="3">
   <x-card data-title="CheckoutForm" data-icon="lucide:credit-card" data-href="/components/checkout/checkout-form">
-    The fundamental component for processing payments. It takes a `paymentLink` or `checkoutSession` ID and renders the complete payment UI.
+    The primary component for handling payment links and checkout sessions. It supports various display modes, including inline, standalone, and popup.
   </x-card>
   <x-card data-title="CheckoutTable" data-icon="lucide:table" data-href="/components/checkout/checkout-table">
-    Displays a complete pricing table. When a user selects a plan, it automatically initiates a checkout session and renders the payment form.
+    Renders a complete pricing table and manages the checkout flow when a user selects a plan, automatically creating a session and displaying the payment form.
   </x-card>
   <x-card data-title="CheckoutDonate" data-icon="lucide:heart-handshake" data-href="/components/checkout/checkout-donate">
-    A flexible component for adding donation functionality. It handles donation setup, displays supporter history, and manages the donation payment flow.
+    Implements donation functionality with flexible options for display modes, supporter history, and customization, guiding the user through the donation process.
   </x-card>
-</x-cards>
-
-Each of these components is designed to be highly customizable and can be integrated seamlessly into your application. Click on any card to view its detailed documentation and usage examples.
+</x-cards>

package/docs/components-ui-form-elements-phone-input.ja.md

@@ -8,8 +8,8 @@
 
 このコンポーネントは、`react-international-phone`ライブラリをコア機能として活用し、それをラップして`react-hook-form`およびMaterial-UIとの深い統合を提供します。ユーザーが国を選択したり番号を入力したりすると、コンポーネントはフォームの状態にある対応するフィールドを更新します。また、他のコンポーネントがフォーム内のリンクされた国フィールドを変更すると、自動的に国選択を更新します。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![PhoneInput](assets/diagram/phone-input-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
+![PhoneInput](assets/diagram/phone-input-diagram-0.ja.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## Props

package/docs/components-ui-form-elements-phone-input.md

@@ -8,7 +8,7 @@ This component is designed to work in tandem with other form elements, such as t
 
 The component leverages the `react-international-phone` library for its core functionality and wraps it to provide deep integration with `react-hook-form` and Material-UI. When a user selects a country or types a number, the component updates the corresponding fields in the form state. It also automatically updates its country selection when another component modifies the linked country field in the form.
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
 ![PhoneInput](assets/diagram/phone-input-diagram-0.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 

package/docs/components-ui-form-elements-phone-input.zh-TW.md

@@ -8,8 +8,8 @@
 
 該元件利用 `react-international-phone` 函式庫實現其核心功能，並將其包裝以提供與 `react-hook-form` 和 Material-UI 的深度整合。當使用者選擇一個國家或輸入號碼時，該元件會更新表單狀態中對應的欄位。當另一個元件修改表單中連結的國家欄位時，它也會自動更新其國家選擇。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![PhoneInput](assets/diagram/phone-input-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
+![PhoneInput](assets/diagram/phone-input-diagram-0.zh-TW.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## 屬性

package/docs/components-ui-form-elements-phone-input.zh.md

@@ -8,8 +8,8 @@
 
 该组件利用 `react-international-phone` 库实现其核心功能，并对其进行包装，以提供与 `react-hook-form` 和 Material-UI 的深度集成。当用户选择一个国家或输入一个号码时，该组件会更新表单状态中相应的字段。当另一个组件修改表单中链接的国家字段时，它也会自动更新其国家选择。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![PhoneInput](assets/diagram/phone-input-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9::1764919317 -->
+![PhoneInput](assets/diagram/phone-input-diagram-0.zh.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## Props

package/docs/components.ja.md

@@ -8,8 +8,8 @@
 
 次の図は、高レベルのコンポーネントが通常どのように相互作用するかを示しています。`CheckoutTable` や `CheckoutDonate` のようなユーザー向けのコンポーネントがエントリーポイントとして機能し、その後、コアの `CheckoutForm` を利用して最終的な支払い処理を行います。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![Components](assets/diagram/components-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
+![Components](assets/diagram/components-diagram-0.ja.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## コンポーネントカテゴリ

package/docs/components.md

@@ -8,7 +8,7 @@ All components are designed to work seamlessly within the `PaymentProvider` cont
 
 The following diagram illustrates how the high-level components typically interact. User-facing components like `CheckoutTable` or `CheckoutDonate` act as entry points, which then utilize the core `CheckoutForm` to handle the final payment processing.
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
 ![Components](assets/diagram/components-diagram-0.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 

package/docs/components.zh-TW.md

@@ -8,8 +8,8 @@
 
 下圖說明了高階元件通常如何互動。面向使用者的元件，如 `CheckoutTable` 或 `CheckoutDonate`，作為入口點，然後利用核心的 `CheckoutForm` 來處理最終的支付處理。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![Components](assets/diagram/components-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
+![Components](assets/diagram/components-diagram-0.zh-TW.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## 元件類別

package/docs/components.zh.md

@@ -8,8 +8,8 @@
 
 下图说明了高级组件通常如何交互。面向用户的组件（如 `CheckoutTable` 或 `CheckoutDonate`）作为入口点，然后利用核心的 `CheckoutForm` 来处理最终的支付流程。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![Components](assets/diagram/components-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
+![Components](assets/diagram/components-diagram-0.zh.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## 组件分类

package/docs/hooks-use-subscription.ja.md

@@ -10,8 +10,8 @@
 
 バックエンドサービスがそのチャネルにイベントを公開すると、フックのサブスクリプションオブジェクトがイベントを発行し、コンポーネントはそれをリッスンできます。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![useSubscription](assets/diagram/use-subscription-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
+![useSubscription](assets/diagram/use-subscription-diagram-0.ja.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## パラメータ

package/docs/hooks-use-subscription.md

@@ -12,7 +12,7 @@ When the backend service publishes an event to that channel, the hook's subscrip
 
 The following diagram illustrates this data flow:
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
 ![useSubscription](assets/diagram/use-subscription-diagram-0.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 

package/docs/hooks-use-subscription.zh-TW.md

@@ -10,8 +10,8 @@
 
 當後端服務向該頻道發布事件時，此 hook 的訂閱物件會發出該事件，您的元件可以監聽該事件。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![useSubscription](assets/diagram/use-subscription-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
+![useSubscription](assets/diagram/use-subscription-diagram-0.zh-TW.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## 參數

package/docs/hooks-use-subscription.zh.md

@@ -10,8 +10,8 @@
 
 当后端服务向该通道发布事件时，Hook 的订阅对象会发出该事件，您的组件可以监听该事件。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![useSubscription](assets/diagram/use-subscription-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
+![useSubscription](assets/diagram/use-subscription-diagram-0.zh.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## 参数

package/docs/overview.ja.md

@@ -26,45 +26,9 @@
 
 このライブラリは、プロバイダーコンポーネントモデルを中心に設計されています。`PaymentProvider` はライブラリの中核であり、認証、API通信、状態を管理するコンテキストを作成します。他のすべての決済コンポーネントは、正しく機能するためにこのプロバイダーでラップする必要があります。これにより、決済ロジックが一元化され、個々のコンポーネントは軽量で特定の機能に集中できます。
 
-```d2 高レベルアーキテクチャ
-direction: down
-
-User: {
-  shape: c4-person
-}
-
-Your-Application: {
-  label: "あなたのアプリケーション"
-  shape: rectangle
-
-  PaymentProvider: {
-    label: "PaymentProvider"
-    shape: rectangle
-
-    Payment-Components: {
-      label: "決済コンポーネント"
-      shape: rectangle
-      grid-columns: 2
-
-      CheckoutForm: { label: "CheckoutForm" }
-      CheckoutTable: { label: "CheckoutTable" }
-      CheckoutDonate: { label: "CheckoutDonate" }
-      CustomerInvoiceList: { label: "CustomerInvoiceList" }
-    }
-  }
-}
-
-Payment-Kit-Backend: {
-  label: "Payment Kit バックエンド"
-  shape: cylinder
-}
-
-User -> Your-Application.PaymentProvider.Payment-Components: "UIと対話する"
-Your-Application.PaymentProvider -> Payment-Kit-Backend: "API通信を処理する"
-Payment-Kit-Backend -> Your-Application.PaymentProvider: "データを返す"
-Your-Application.PaymentProvider.Payment-Components -> User: "UIの更新をレンダリングする"
-
-```
+<!-- DIAGRAM_IMAGE_START:architecture:16:9::1765377042 -->
+![Overview](assets/diagram/overview-01.ja.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
 ## 構築できるもの
 

package/docs/overview.md

@@ -1,80 +1,49 @@
 # Overview
 
-`@blocklet/payment-react` is a comprehensive React component library designed to streamline the integration of payment flows, subscriptions, and donation systems into your blocklets. Built on top of [Payment Kit](https://www.arcblock.io/docs/arcblock-payment-kit), it provides a suite of pre-built, customizable, and production-ready components to help you build powerful payment experiences with minimal effort.
+This document provides a high-level overview of the `@blocklet/payment-react` library. By the end of this guide, you will understand its core features, architecture, and the types of payment functionalities you can build with it. This library is designed to simplify the integration of payment flows, subscriptions, and donation systems into React applications by interfacing with the Blocklet Payment Kit.
 
 ## Key Features
 
-<x-cards data-columns="3">
+The library offers a comprehensive set of tools to accelerate the development of payment-related features.
+
+<x-cards data-columns="2">
   <x-card data-title="Pre-built UI Components" data-icon="lucide:layout-template">
-    Includes a rich set of components like checkout forms, pricing tables, and donation widgets to cover common payment scenarios out of the box.
+    A suite of ready-to-use components, including checkout forms, pricing tables, and donation widgets, to handle common payment workflows.
   </x-card>
   <x-card data-title="Customizable Themes" data-icon="lucide:palette">
-    Gain full control over the look and feel of your payment flows using Material-UI themes, ensuring a consistent user experience.
-  </x-card>
-  <x-card data-title="i18n Support" data-icon="lucide:languages">
-    Built-in internationalization support allows you to easily localize component text for a global audience.
+    Leverages Material-UI for theming, allowing for extensive customization to match your application's design system.
   </x-card>
   <x-card data-title="Comprehensive Payment Operations" data-icon="lucide:credit-card">
-    Easily handle complex payment logic, including subscriptions, refunds, invoice management, and metered billing.
+    Supports a wide range of payment operations such as subscriptions, invoice management, refunds, and metered billing.
   </x-card>
-  <x-card data-title="Optimized Performance" data-icon="lucide:package-minus">
-    Optimize your application's bundle size and improve performance with built-in support for lazy loading and dynamic component imports.
+  <x-card data-title="Internationalization (i18n)" data-icon="lucide:languages">
+    Includes built-in support for multiple languages, enabling you to create a localized experience for a global user base.
   </x-card>
 </x-cards>
 
 ## How It Works
 
-The library is architected around a provider-component model. The `PaymentProvider` is the core of the library, creating a context that manages authentication, API communication, and state. All other payment components must be wrapped within this provider to function correctly. This centralizes the payment logic and makes individual components lightweight and focused.
-
-```d2 High-Level Architecture
-direction: down
-
-User: {
-  shape: c4-person
-}
-
-Your-Application: {
-  label: "Your Application"
-  shape: rectangle
+`@blocklet/payment-react` operates on a provider-component model. The `PaymentProvider` component is central to the library's functionality. It establishes a React context that manages API communication, state, and session information. All other payment-related components must be nested within a `PaymentProvider` to function correctly. This architecture centralizes critical logic, ensuring that components are decoupled and focused on their specific UI tasks.
 
-  PaymentProvider: {
-    label: "PaymentProvider"
-    shape: rectangle
+The diagram below illustrates the high-level data flow. User interactions with payment components trigger API calls handled by the `PaymentProvider`, which communicates with the Payment Kit backend and updates the UI with the response.
 
-    Payment-Components: {
-      label: "Payment Components"
-      shape: rectangle
-      grid-columns: 2
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1765377042 -->
+![Overview](assets/diagram/overview-01.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
-      CheckoutForm: { label: "CheckoutForm" }
-      CheckoutTable: { label: "CheckoutTable" }
-      CheckoutDonate: { label: "CheckoutDonate" }
-      CustomerInvoiceList: { label: "CustomerInvoiceList" }
-    }
-  }
-}
+## Available Components
 
-Payment-Kit-Backend: {
-  label: "Payment Kit Backend"
-  shape: cylinder
-}
+The library is organized into several categories of components and utilities to address different aspects of building a payment system.
 
-User -> Your-Application.PaymentProvider.Payment-Components: "Interacts with UI"
-Your-Application.PaymentProvider -> Payment-Kit-Backend: "Handles API Communication"
-Payment-Kit-Backend -> Your-Application.PaymentProvider: "Returns Data"
-Your-Application.PaymentProvider.Payment-Components -> User: "Renders UI Updates"
-
-```
-
-## What You Can Build
-
-- **Subscription Services:** Quickly implement pricing pages and checkout flows for SaaS products using `CheckoutTable`.
-- **E-commerce Checkouts:** Build one-time payment forms for selling goods with `CheckoutForm`.
-- **Donation Systems:** Add flexible donation widgets to support creators or causes with `CheckoutDonate`.
-- **Customer Portals:** Display invoice history and manage payment methods for users with `CustomerInvoiceList` and other history components.
+| Category | Description | Key Components |
+| --- | --- | --- |
+| **Providers** | Context providers that wrap your application to enable payment features. | `PaymentProvider`, `DonateProvider` |
+| **Checkout Components** | High-level components for complete payment and donation flows. | `CheckoutForm`, `CheckoutTable`, `CheckoutDonate` |
+| **UI Components** | Granular components for building custom payment user interfaces. | `PricingTable`, `PaymentSummary`, `AddressForm` |
+| **History Components** | Components for displaying historical data like invoices and payments. | `CustomerInvoiceList`, `CustomerPaymentList` |
+| **Business Logic** | Specialized components for managing subscriptions and overdue payments. | `ResumeSubscription`, `OverdueInvoicePayment` |
+| **Hooks & Utilities** | Custom hooks and utility functions for interacting with the payment service. | `useSubscription`, `api`, `dayjs` |
 
 ## Next Steps
 
-Now that you have an overview of what `@blocklet/payment-react` offers, the best way to learn is by building something.
-
-Dive into our [Getting Started](./getting-started.md) guide to install the library and create your first payment form in minutes.
+To begin implementing payment features, proceed to the [Getting Started](./getting-started.md) guide, which provides step-by-step instructions for installation and building a basic payment form.

package/docs/overview.zh-TW.md

@@ -26,45 +26,9 @@
 
 此函式庫圍繞著提供者-元件模型架構。`PaymentProvider` 是此函式庫的核心，它建立了一個管理身份驗證、API 通訊和狀態的上下文 (context)。所有其他支付元件都必須包裹在此提供者內才能正常運作。這種方式集中了支付邏輯，並使個別元件保持輕量和專注。
 
-```d2 高階架構
-direction: down
-
-User: {
-  shape: c4-person
-}
-
-Your-Application: {
-  label: "Your Application"
-  shape: rectangle
-
-  PaymentProvider: {
-    label: "PaymentProvider"
-    shape: rectangle
-
-    Payment-Components: {
-      label: "Payment Components"
-      shape: rectangle
-      grid-columns: 2
-
-      CheckoutForm: { label: "CheckoutForm" }
-      CheckoutTable: { label: "CheckoutTable" }
-      CheckoutDonate: { label: "CheckoutDonate" }
-      CustomerInvoiceList: { label: "CustomerInvoiceList" }
-    }
-  }
-}
-
-Payment-Kit-Backend: {
-  label: "Payment Kit Backend"
-  shape: cylinder
-}
-
-User -> Your-Application.PaymentProvider.Payment-Components: "Interacts with UI"
-Your-Application.PaymentProvider -> Payment-Kit-Backend: "Handles API Communication"
-Payment-Kit-Backend -> Your-Application.PaymentProvider: "Returns Data"
-Your-Application.PaymentProvider.Payment-Components -> User: "Renders UI Updates"
-
-```
+<!-- DIAGRAM_IMAGE_START:architecture:16:9::1765377042 -->
+![Overview](assets/diagram/overview-01.zh-TW.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
 ## 您可以建立什麼
 

package/docs/overview.zh.md

@@ -26,45 +26,9 @@
 
 该库围绕提供者-组件模型构建。`PaymentProvider` 是该库的核心，它创建了一个管理身份验证、API 通信和状态的上下文。所有其他支付组件都必须在此提供者内包装才能正常工作。这种方式集中了支付逻辑，并使各个组件保持轻量和专注。
 
-```d2 High-Level Architecture
-direction: down
-
-User: {
-  shape: c4-person
-}
-
-Your-Application: {
-  label: "你的应用"
-  shape: rectangle
-
-  PaymentProvider: {
-    label: "PaymentProvider"
-    shape: rectangle
-
-    Payment-Components: {
-      label: "支付组件"
-      shape: rectangle
-      grid-columns: 2
-
-      CheckoutForm: { label: "CheckoutForm" }
-      CheckoutTable: { label: "CheckoutTable" }
-      CheckoutDonate: { label: "CheckoutDonate" }
-      CustomerInvoiceList: { label: "CustomerInvoiceList" }
-    }
-  }
-}
-
-Payment-Kit-Backend: {
-  label: "Payment Kit 后端"
-  shape: cylinder
-}
-
-User -> Your-Application.PaymentProvider.Payment-Components: "与 UI 交互"
-Your-Application.PaymentProvider -> Payment-Kit-Backend: "处理 API 通信"
-Payment-Kit-Backend -> Your-Application.PaymentProvider: "返回数据"
-Your-Application.PaymentProvider.Payment-Components -> User: "渲染 UI 更新"
-
-```
+<!-- DIAGRAM_IMAGE_START:architecture:16:9::1765377042 -->
+![Overview](assets/diagram/overview-01.zh.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
 ## 你可以构建什么
 

package/docs/providers-payment-provider.ja.md

@@ -8,8 +8,8 @@
 
 このプロバイダーは、マウント時にPayment Kitのバックエンドから設定データを初期化して取得します。このデータは、ユーザーのセッションやその他のユーティリティとともに、`usePaymentContext`フックを介してすべての子孫コンポーネントで利用可能になります。このパターンにより、支払いコンポーネントはプロップのバケツリレー（prop drilling）なしで、常に必要なコンテキストにアクセスできるようになります。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![PaymentProvider](assets/diagram/payment-provider-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
+![PaymentProvider](assets/diagram/payment-provider-diagram-0.ja.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## セットアップと使用法

package/docs/providers-payment-provider.md

@@ -10,7 +10,7 @@ The provider initializes and fetches configuration data from the Payment Kit bac
 
 The following diagram illustrates this flow:
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
 ![PaymentProvider](assets/diagram/payment-provider-diagram-0.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 

package/docs/providers-payment-provider.zh-TW.md

@@ -8,8 +8,8 @@
 
 該提供者在掛載時會初始化並從 Payment Kit 後端取得設定資料。這些資料，連同使用者的 session 和其他工具，會透過 `usePaymentContext` 掛鉤提供給任何後代元件。這種模式確保您的支付元件始終能夠存取必要的上下文，而無需透過屬性傳遞。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![PaymentProvider](assets/diagram/payment-provider-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
+![PaymentProvider](assets/diagram/payment-provider-diagram-0.zh-TW.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## 設定與使用

package/docs/providers-payment-provider.zh.md

@@ -8,8 +8,8 @@
 
 提供者在挂载时会初始化并从 Payment Kit 后端获取配置数据。这些数据连同用户会话和其他实用工具，通过 `usePaymentContext` 钩子提供给任何后代组件。这种模式确保您的支付组件始终能够访问必要的上下文，而无需进行属性钻取（prop drilling）。
 
-<!-- DIAGRAM_IMAGE_START:architecture:16:9 -->
-![PaymentProvider](assets/diagram/payment-provider-diagram-0.jpg)
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1764919317 -->
+![PaymentProvider](assets/diagram/payment-provider-diagram-0.zh.jpg)
 <!-- DIAGRAM_IMAGE_END -->
 
 ## 设置和使用

package/docs/providers.ja.md

@@ -4,29 +4,9 @@ Context Provider は `@blocklet/payment-react` の中心的な概念です。こ
 
 このライブラリのほとんどのコンポーネントを使用するには、アプリケーションまたは関連ページを適切なプロバイダーでラップする必要があります。
 
-```d2 基本的なプロバイダー構造 icon=graph:flowchart
-direction: down
-
-あなたのアプリケーション: {
-  shape: rectangle
-
-  PaymentProvider: {
-    label: "PaymentProvider"
-    shape: rectangle
-
-    CheckoutForm: {
-      label: "CheckoutForm"
-    }
-    CustomerInvoiceList: {
-      label: "CustomerInvoiceList"
-    }
-  }
-}
-
-あなたのアプリケーション -> PaymentProvider: "ラップする"
-PaymentProvider -> CheckoutForm: "コンテキストを提供"
-PaymentProvider -> CustomerInvoiceList: "コンテキストを提供"
-```
+<!-- DIAGRAM_IMAGE_START:architecture:16:9::1765377042 -->
+![Providers](assets/diagram/providers-01.ja.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
 このライブラリは、それぞれ異なる目的を果たす2つの主要なプロバイダーを提供しています。ニーズに合ったものを選択してください。
 

package/docs/providers.md

@@ -1,42 +1,24 @@
 # Providers
 
-Context Providers are a core concept in `@blocklet/payment-react`. They act as wrappers around parts of your application, using React's Context API to pass down essential data and functions to all the components nested within them. This avoids the need to pass props down manually through many levels of your component tree.
+To enable payment functionalities in your application, you must first wrap your components with the appropriate context providers. These providers use React's Context API to supply essential data and functions throughout your component tree, eliminating the need to pass props down manually.
 
-To use most of the components in this library, you must wrap your application or relevant pages with the appropriate provider.
+Nearly all components in `@blocklet/payment-react` depend on a provider to function correctly. Wrapping your application or a specific page in a provider makes payment settings, user session information, and API clients available to all nested payment components.
 
-```d2 Basic Provider Structure icon=graph:flowchart
-direction: down
+The following diagram illustrates how these providers wrap your application components:
 
-Your-Application: {
-  shape: rectangle
+<!-- DIAGRAM_IMAGE_START:architecture:16:9:1765377042 -->
+![Providers](assets/diagram/providers-01.jpg)
+<!-- DIAGRAM_IMAGE_END -->
 
-  PaymentProvider: {
-    label: "PaymentProvider"
-    shape: rectangle
+The library includes two primary providers, each designed for a specific use case.
 
-    CheckoutForm: {
-      label: "CheckoutForm"
-    }
-    CustomerInvoiceList: {
-      label: "CustomerInvoiceList"
-    }
-  }
-}
-
-Your-Application -> PaymentProvider: "Wraps"
-PaymentProvider -> CheckoutForm: "Provides context"
-PaymentProvider -> CustomerInvoiceList: "Provides context"
-```
-
-The library offers two main providers, each serving a distinct purpose. Choose the one that fits your needs.
-
-<x-cards>
+<x-cards data-columns="2">
   <x-card data-title="PaymentProvider" data-icon="lucide:package" data-href="/providers/payment-provider">
-    The fundamental provider required for nearly all payment-related operations. It manages payment methods, currency settings, user session information, and provides a pre-configured API client.
+    The core provider required for all standard payment operations. It manages payment methods, currency settings, API access, and user session data.
   </x-card>
   <x-card data-title="DonateProvider" data-icon="lucide:heart" data-href="/providers/donate-provider">
-    A specialized provider for donation features. It handles the configuration and state for donation widgets, such as those implemented with the CheckoutDonate component.
+    A specialized provider for donation features. It handles the unique settings and state management for donation components like `CheckoutDonate`.
   </x-card>
 </x-cards>
 
-Click on a provider above to view its detailed documentation, including required props and setup examples.
+For detailed setup instructions and available properties, please refer to the documentation for each specific provider.