@blocklet/payment-react 1.19.22 → 1.20.0

package/.aigne/doc-smith/config.yaml

@@ -0,0 +1,114 @@
+# Project information for documentation publishing
+projectName: "Payment Kit React Components"
+projectDesc: "A React component library for building payment flows, subscriptions, and donation systems in blocklets, seamlessly integrated with Payment Kit."
+projectLogo: 
+
+# =============================================================================
+# Documentation Configuration
+# =============================================================================
+
+# Purpose: What's the main outcome you want readers to achieve?
+# Available options (uncomment and modify as needed):
+#   getStarted       - Get started quickly: Help new users go from zero to working in <30 minutes
+#   completeTasks    - Complete specific tasks: Guide users through common workflows and use cases
+#   findAnswers      - Find answers fast: Provide searchable reference for all features and APIs
+#   understandSystem - Understand the system: Explain how it works, why design decisions were made
+#   solveProblems    - Solve problems: Help users troubleshoot and fix issues
+#   mixedPurpose     - Mix of above: Comprehensive documentation covering multiple needs
+documentPurpose:
+  - getStarted
+  - completeTasks
+
+# Target Audience: Who will be reading this most often?
+# Available options (uncomment and modify as needed):
+#   endUsers         - End users (non-technical): People who use the product but don't code
+#   developers       - Developers integrating: Engineers adding this to their projects
+#   devops           - DevOps/Infrastructure: Teams deploying, monitoring, maintaining systems
+#   decisionMakers   - Technical decision makers: Architects, leads evaluating or planning implementation
+#   supportTeams     - Support teams: People helping others use the product
+#   mixedTechnical   - Mixed technical audience: Developers, DevOps, and technical users
+targetAudienceTypes:
+  - developers
+
+# Reader Knowledge Level: What do readers typically know when they arrive?
+# Available options (uncomment and modify as needed):
+#   completeBeginners    - Complete beginners: New to this domain/technology entirely
+#   domainFamiliar       - Domain-familiar, tool-new: Know the problem space, new to this specific solution
+#   experiencedUsers     - Experienced users: Regular users needing reference/advanced topics
+#   emergencyTroubleshooting - Emergency/troubleshooting: Something's broken, need to fix it quickly
+#   exploringEvaluating  - Exploring/evaluating: Trying to understand if this fits their needs
+readerKnowledgeLevel: completeBeginners
+
+# Documentation Depth: How comprehensive should the documentation be?
+# Available options (uncomment and modify as needed):
+#   essentialOnly      - Essential only: Cover the 80% use cases, keep it concise
+#   balancedCoverage   - Balanced coverage: Good depth with practical examples [RECOMMENDED]
+#   comprehensive      - Comprehensive: Cover all features, edge cases, and advanced scenarios
+#   aiDecide           - Let AI decide: Analyze code complexity and suggest appropriate depth
+documentationDepth: balancedCoverage
+
+# Custom Rules: Define specific documentation generation rules and requirements
+rules: |
+  The generated documentation should focus on React component usage, not RFC-style specifications.
+  
+  ## Documentation Scope
+  - **Focus on Key Components Only** - Document only the most important and frequently used components
+  - Prioritize core payment flow components over utility components
+  
+  ## Component Documentation Requirements
+  For each React component, document:
+  1. **Input Parameters (Props)** - All props with types, descriptions, and required/optional status
+  2. **Usage Scenarios** - Different ways to pass parameters for various use cases and their effects
+  3. **Implementation-Based Logic** - Strictly follow the actual component implementation to avoid hallucinations
+  4. **Integration Examples** - Complete working examples showing proper component integration
+  
+  ## Provider Integration
+  - **PaymentProvider and DonateProvider**: Document how to use these providers and integrate with components
+  - **Context Requirements**: Explain which components need to be wrapped by which providers
+  - **Example**: If user needs CheckoutForm, document that it must be wrapped with PaymentProvider
+  - Show complete integration patterns with provider setup
+  
+  ## Key Components to Prioritize
+  - **Core Payment**: Payment, CheckoutForm, CheckoutDonate, CheckoutTable
+  - **Payment Integration**: StripeForm, PaymentSummary
+  - **Essential Forms**: AddressForm, CurrencySelector, PhoneInput, CountrySelect
+  - **Critical UI**: PricingTable
+  - **History Components**: CustomerInvoiceList, CustomerPaymentList, CreditGrantsList, CreditTransactionsList
+  - **Business Components**: OverdueInvoicePayment, ResumeSubscription
+  - **Utility Components**: SafeGuard
+  - **Provider Components**: PaymentProvider, DonateProvider
+  - **Price/Amount Utilities**: Key formatting functions from util.ts
+  - **Status/Display Utilities**: Status and display formatting functions from util.ts
+  
+  ## Documentation Structure
+  - Component overview and purpose
+  - Props interface with detailed explanations
+  - Usage scenarios with different prop combinations
+  - Integration examples with providers
+  - Best practices and common patterns
+  
+  ## Content Rules
+  - Use async/await for asynchronous examples
+  - Show complete, runnable code examples
+  - Include TypeScript prop interfaces
+  - Document provider requirements clearly
+  - Base all descriptions on actual component implementation
+  
+  The documentation process can use tests for examples, but do not generate docs for test files themselves.
+# Target Audience: Describe your specific target audience and their characteristics  
+targetAudience: |
+  Frontend developers integrating payment functionality into React applications.
+  Expected to have React/TypeScript experience and basic understanding of payment workflows. 
+
+locale: en
+# translateLanguages:  # List of languages to translate the documentation to
+#   - zh  # Example: Chinese translation
+#   - en  # Example: English translation
+docsDir: ./docs  # Directory to save generated documentation
+sourcesPath:  # Source code paths to analyze
+  - ./src
+  - ./README.md
+lastGitHead: b00994d8ace7e6031e09282eab73a4e7509468dc
+# appUrl: "https://www.staging.arcblock.io/"
+appUrl: "https://www.arcblock.io"
+boardId: "payment-kit-react"

package/.aigne/doc-smith/output/structure-plan.json

@@ -0,0 +1,361 @@
+[
+  {
+    "title": "Overview",
+    "description": "An overview of the @blocklet/payment-react library, its key features, and how it helps in building payment flows.",
+    "path": "/overview",
+    "parentId": null,
+    "sourceIds": [
+      "README.md",
+      "src/index.ts"
+    ]
+  },
+  {
+    "title": "Getting Started",
+    "description": "A step-by-step guide to installing the library and building a minimal, functional payment form.",
+    "path": "/getting-started",
+    "parentId": null,
+    "sourceIds": [
+      "README.md",
+      "src/contexts/payment.tsx",
+      "src/checkout/form.tsx",
+      "src/theme/index.tsx"
+    ]
+  },
+  {
+    "title": "Providers",
+    "description": "Documentation for the context providers that are essential for wrapping your application and enabling payment functionalities.",
+    "path": "/providers",
+    "parentId": null,
+    "sourceIds": [
+      "src/contexts/payment.tsx",
+      "src/contexts/donate.tsx",
+      "README.md"
+    ]
+  },
+  {
+    "title": "PaymentProvider",
+    "description": "Detailed documentation for the `PaymentProvider` component, which is required to use most of the library's features.",
+    "path": "/providers/payment-provider",
+    "parentId": "/providers",
+    "sourceIds": [
+      "src/contexts/payment.tsx",
+      "README.md"
+    ]
+  },
+  {
+    "title": "DonateProvider",
+    "description": "Learn how to use the `DonateProvider` to manage state and settings for donation-related components.",
+    "path": "/providers/donate-provider",
+    "parentId": "/providers",
+    "sourceIds": [
+      "src/contexts/donate.tsx",
+      "README.md"
+    ]
+  },
+  {
+    "title": "Components",
+    "description": "Explore the core components for building different types of payment and checkout experiences.",
+    "path": "/components",
+    "parentId": null,
+    "sourceIds": [
+      "src/index.ts",
+      "README.md"
+    ]
+  },
+  {
+    "title": "Checkout Components",
+    "description": "High-level components that serve as entry points for various checkout flows like standard payments, pricing tables, and donations.",
+    "path": "/components/checkout",
+    "parentId": "/components",
+    "sourceIds": [
+      "src/checkout/form.tsx",
+      "src/checkout/table.tsx",
+      "src/checkout/donate.tsx"
+    ]
+  },
+  {
+    "title": "CheckoutForm",
+    "description": "The primary component for handling payment links and checkout sessions, supporting various modes like inline, standalone, and popup.",
+    "path": "/components/checkout/checkout-form",
+    "parentId": "/components/checkout",
+    "sourceIds": [
+      "src/checkout/form.tsx",
+      "src/payment/index.tsx",
+      "src/types/index.ts",
+      "src/payment/donation-form.tsx"
+    ]
+  },
+  {
+    "title": "CheckoutTable",
+    "description": "A component that renders a complete pricing table and handles the checkout flow when a user selects a plan.",
+    "path": "/components/checkout/checkout-table",
+    "parentId": "/components/checkout",
+    "sourceIds": [
+      "src/checkout/table.tsx",
+      "src/components/pricing-table.tsx"
+    ]
+  },
+  {
+    "title": "CheckoutDonate",
+    "description": "Implement donation functionality with this flexible component, supporting various display modes and customization options.",
+    "path": "/components/checkout/checkout-donate",
+    "parentId": "/components/checkout",
+    "sourceIds": [
+      "src/checkout/donate.tsx",
+      "src/contexts/donate.tsx",
+      "README.md"
+    ]
+  },
+  {
+    "title": "UI Components",
+    "description": "Components designed to build specific parts of the payment UI, offering granular control over the user experience.",
+    "path": "/components/ui",
+    "parentId": "/components",
+    "sourceIds": [
+      "src/components/pricing-table.tsx",
+      "src/payment/summary.tsx",
+      "src/payment/form/address.tsx",
+      "src/payment/form/phone.tsx",
+      "src/components/country-select.tsx",
+      "src/payment/form/currency.tsx"
+    ]
+  },
+  {
+    "title": "PricingTable",
+    "description": "Display subscription plans and pricing options in a structured table, allowing users to select and proceed to checkout.",
+    "path": "/components/ui/pricing-table",
+    "parentId": "/components/ui",
+    "sourceIds": [
+      "src/components/pricing-table.tsx",
+      "src/contexts/payment.tsx"
+    ]
+  },
+  {
+    "title": "PaymentSummary",
+    "description": "Show a detailed summary of the order, including line items, totals, and trial information within the checkout flow.",
+    "path": "/components/ui/payment-summary",
+    "parentId": "/components/ui",
+    "sourceIds": [
+      "src/payment/summary.tsx",
+      "src/payment/product-item.tsx",
+      "src/payment/amount.tsx"
+    ]
+  },
+  {
+    "title": "Form Elements",
+    "description": "A collection of granular input components for building custom payment and contact information forms.",
+    "path": "/components/ui/form-elements",
+    "parentId": "/components/ui",
+    "sourceIds": [
+      "src/payment/form/address.tsx",
+      "src/payment/form/phone.tsx",
+      "src/components/country-select.tsx",
+      "src/payment/form/currency.tsx",
+      "src/components/input.tsx",
+      "src/components/label.tsx"
+    ]
+  },
+  {
+    "title": "AddressForm",
+    "description": "A pre-built form for collecting billing address details, with validation based on the selected country.",
+    "path": "/components/ui/form-elements/address-form",
+    "parentId": "/components/ui/form-elements",
+    "sourceIds": [
+      "src/payment/form/address.tsx",
+      "src/components/country-select.tsx",
+      "src/libs/validator.ts"
+    ]
+  },
+  {
+    "title": "PhoneInput",
+    "description": "An international phone number input with country code selection and validation.",
+    "path": "/components/ui/form-elements/phone-input",
+    "parentId": "/components/ui/form-elements",
+    "sourceIds": [
+      "src/payment/form/phone.tsx",
+      "src/libs/phone-validator.ts",
+      "src/components/country-select.tsx"
+    ]
+  },
+  {
+    "title": "CountrySelect",
+    "description": "A dropdown component for selecting a country, complete with country flags and search functionality.",
+    "path": "/components/ui/form-elements/country-select",
+    "parentId": "/components/ui/form-elements",
+    "sourceIds": [
+      "src/components/country-select.tsx"
+    ]
+  },
+  {
+    "title": "CurrencySelector",
+    "description": "A component that allows users to select their preferred payment currency from a list of available options.",
+    "path": "/components/ui/form-elements/currency-selector",
+    "parentId": "/components/ui/form-elements",
+    "sourceIds": [
+      "src/payment/form/currency.tsx"
+    ]
+  },
+  {
+    "title": "Business Logic Components",
+    "description": "Specialized components that encapsulate complex business logic for subscription and invoice management.",
+    "path": "/components/business",
+    "parentId": "/components",
+    "sourceIds": [
+      "src/components/over-due-invoice-payment.tsx",
+      "src/components/resume-subscription.tsx",
+      "src/components/auto-topup/index.tsx",
+      "src/components/auto-topup/modal.tsx"
+    ]
+  },
+  {
+    "title": "OverdueInvoicePayment",
+    "description": "A component to handle the payment of overdue invoices for a specific customer or subscription.",
+    "path": "/components/business/overdue-invoice-payment",
+    "parentId": "/components/business",
+    "sourceIds": [
+      "src/components/over-due-invoice-payment.tsx",
+      "README.md"
+    ]
+  },
+  {
+    "title": "ResumeSubscription",
+    "description": "A component that allows users to resume a canceled subscription, including handling re-staking if required.",
+    "path": "/components/business/resume-subscription",
+    "parentId": "/components/business",
+    "sourceIds": [
+      "src/components/resume-subscription.tsx",
+      "README.md"
+    ]
+  },
+  {
+    "title": "Auto-Topup Components",
+    "description": "Components for managing and configuring the automatic credit top-up functionality, including a display card and a configuration modal.",
+    "path": "/components/business/auto-topup",
+    "parentId": "/components/business",
+    "sourceIds": [
+      "README.md",
+      "src/components/auto-topup/index.tsx",
+      "src/components/auto-topup/modal.tsx",
+      "src/components/auto-topup/product-card.tsx"
+    ]
+  },
+  {
+    "title": "History Components",
+    "description": "Components dedicated to displaying historical data such as invoices, payments, and credit grants.",
+    "path": "/components/history",
+    "parentId": "/components",
+    "sourceIds": [
+      "src/history/invoice/list.tsx",
+      "src/history/payment/list.tsx",
+      "src/history/credit/grants-list.tsx",
+      "src/history/credit/transactions-list.tsx"
+    ]
+  },
+  {
+    "title": "CustomerInvoiceList",
+    "description": "Render a list of a customer's invoices with details on status, amount, and creation date.",
+    "path": "/components/history/invoice-list",
+    "parentId": "/components/history",
+    "sourceIds": [
+      "src/history/invoice/list.tsx",
+      "README.md"
+    ]
+  },
+  {
+    "title": "CustomerPaymentList",
+    "description": "Display a customer's payment history, including transaction details and status.",
+    "path": "/components/history/payment-list",
+    "parentId": "/components/history",
+    "sourceIds": [
+      "src/history/payment/list.tsx",
+      "README.md"
+    ]
+  },
+  {
+    "title": "CreditGrantsList",
+    "description": "Show a list of credit grants for a customer, including status, remaining amount, and effective dates.",
+    "path": "/components/history/credit-grants-list",
+    "parentId": "/components/history",
+    "sourceIds": [
+      "src/history/credit/grants-list.tsx"
+    ]
+  },
+  {
+    "title": "CreditTransactionsList",
+    "description": "List all credit transactions, providing a detailed log of credit usage and adjustments.",
+    "path": "/components/history/credit-transactions-list",
+    "parentId": "/components/history",
+    "sourceIds": [
+      "src/history/credit/transactions-list.tsx"
+    ]
+  },
+  {
+    "title": "Guides",
+    "description": "Guides for advanced topics like theming, using utility functions, and other non-component features.",
+    "path": "/guides",
+    "parentId": null,
+    "sourceIds": [
+      "src/theme/index.tsx",
+      "src/libs/util.ts",
+      "README.md"
+    ]
+  },
+  {
+    "title": "Theming",
+    "description": "Learn how to customize the appearance of payment components using the built-in theme provider and Material-UI theme options.",
+    "path": "/guides/theming",
+    "parentId": "/guides",
+    "sourceIds": [
+      "src/theme/index.tsx",
+      "src/theme/index.css",
+      "src/theme/typography.ts",
+      "src/theme/types.ts",
+      "README.md"
+    ]
+  },
+  {
+    "title": "Utilities",
+    "description": "A reference for utility functions provided by the library, including cached requests, and date formatting.",
+    "path": "/guides/utilities",
+    "parentId": "/guides",
+    "sourceIds": [
+      "README.md",
+      "src/libs/cached-request.ts",
+      "src/libs/dayjs.ts",
+      "src/libs/util.ts",
+      "src/libs/validator.ts",
+      "src/locales/index.tsx"
+    ]
+  },
+  {
+    "title": "Hooks",
+    "description": "Documentation for the custom React hooks provided by the library for handling specific functionalities.",
+    "path": "/hooks",
+    "parentId": null,
+    "sourceIds": [
+      "src/hooks/subscription.ts",
+      "src/hooks/mobile.ts",
+      "README.md"
+    ]
+  },
+  {
+    "title": "useSubscription",
+    "description": "A hook for subscribing to real-time events from the payment service, such as 'invoice.paid'.",
+    "path": "/hooks/use-subscription",
+    "parentId": "/hooks",
+    "sourceIds": [
+      "src/hooks/subscription.ts",
+      "README.md"
+    ]
+  },
+  {
+    "title": "useMobile",
+    "description": "A utility hook for detecting if the application is being viewed on a mobile device to enable responsive layouts.",
+    "path": "/hooks/use-mobile",
+    "parentId": "/hooks",
+    "sourceIds": [
+      "src/hooks/mobile.ts",
+      "README.md"
+    ]
+  }
+]

package/.aigne/doc-smith/preferences.yml

@@ -0,0 +1,55 @@
+rules:
+  - id: pref_b8a4986e9903fe0f
+    active: true
+    scope: document
+    rule: 在所有示例中统一`PaymentProvider`的用法，仅展示通过本地`useSessionContext`获取`session`和`connectApi`，并将`useSessionContext`的完整实现细节和声明方式集中定义在`payment-provider.md`文档中。
+    feedback: 所有的示例里对于PaymentProvider的用法应该统一,比如具体的使用都指向payment-context的文档, 然后示例里只写明 const {session,
+      connectApi}=useSessionontext; useSessionContext 说明是指向自己的本地的session文件;
+      至于怎么声明自己的session文件可以写在payment-provider.md文档里:import { createAuthServiceSessionContext } from
+      '@arcblock/did-connect-react/lib/Session';import { useContext } from 'react';const { SessionProvider,
+      SessionContext, SessionConsumer, withSession } = createAuthServiceSessionContext();function useSessionContext()
+      {  const info = useContext(SessionContext);  return info;}export { SessionProvider, SessionContext,
+      SessionConsumer, useSessionContext, withSession };
+    createdAt: 2025-09-01T02:32:25.705Z
+  - id: pref_bf09eebe4c624ab4
+    active: true
+    scope: document
+    rule: 所有代码示例必须保证语法正确和格式无误，确保可以直接复制粘贴运行。
+    feedback: 更新示例中PaymentProvider的用法, 注意示例代码的括号,严格保证示例代码copy出来没有格式错误
+    createdAt: 2025-09-01T02:17:20.214Z
+  - id: pref_805a9242c91fabc6
+    active: true
+    scope: document
+    rule: 在代码示例中，应通过调用 `useSessionContext()` 来获取 `session` 和 `connectApi`，而不是直接 mock 数据。
+    feedback: "我们不应该这么来mock数据,而是告知从 {session, connectApi} = useSessionContext() "
+    createdAt: 2025-09-01T02:05:58.458Z
+  - id: pref_3b490ffac11fd859
+    active: true
+    scope: document
+    rule: 在编写组件示例时，必须严格按照组件本身的属性来实现，确保示例中不使用任何无效的参数。
+    feedback: PaymentProvider并没有serviceHost参数,请你在写示例时严格按照组件本身的属性来实现
+    createdAt: 2025-09-01T01:52:43.445Z
+  - id: pref_5301bb9b58ee36b9
+    active: true
+    scope: document
+    rule: 仅在总览卡片预览中使用 xcard 组件，不要将其用于包含代码示例的内容。
+    feedback: 有代码示例的内容不需要改成xcard组件,展示效果不好,xcards只用于总览的卡片预览
+    createdAt: 2025-09-01T01:36:10.289Z
+  - id: pref_d325528c96a4b7e4
+    active: true
+    scope: document
+    rule: 在组件文档中，确保示例代码包含所有必要的 props 以便运行，并引导用户优先使用集成了子功能的高阶组件。
+    feedback: 1. 示例里 PaymentProvider需要session和connect; 2.鼓励用户直接使用AutoTopup组件,内部集成了Modal
+    createdAt: 2025-08-28T16:01:26.410Z
+  - id: pref_cbe76a82181fabc8
+    active: true
+    scope: structure
+    rule: 将功能紧密相关的组件合并到同一个文档中，而不是为每个组件创建单独的文档。
+    feedback: 我只需要AutoTopUp和AutoTopupModal的组件,并且把这两个放在一个文档里,不需要细分文档
+    createdAt: 2025-08-28T15:32:51.303Z
+  - id: pref_090f6698b82b9d18
+    active: true
+    scope: structure
+    rule: 当新增组件时，必须同步为其生成对应的使用文档。
+    feedback: 我们新增了AutoTopup和AutoTopupModal组件,我们需要把这两个组件的使用也更新生成对应的文档
+    createdAt: 2025-08-28T15:19:56.790Z