@blocklet/payment-react 1.16.0 → 1.16.2

package/README.md

@@ -1,80 +1,314 @@
 # Payment Kit Components
 
+## Quick Start
+
+### 1. Installation
+```bash
+npm install @blocklet/payment-react @mui/material @emotion/react @emotion/styled
+```
+
+### 2. Basic Setup
 ```tsx
-import { CheckoutForm, CheckoutTable, PaymentProvider } from '@blocklet/payment-react';
-import { Paper, Typography } from '@mui/material';
-import React from 'react';
-import { useSearchParams } from 'react-router-dom';
-
-import { useSessionContext } from '../contexts/session';
-
-export default function CheckoutPage() {
-  const [params] = useSearchParams();
-  const { session, connectApi } = useSessionContext();
-
-  if (params.get('type') === 'session') {
-    return (
-      <PaymentProvider session={session} connect={connectApi}>
-        <Typography variant="h4" gutterBottom>
-          Checkout with session
-        </Typography>
-        <Paper sx={{ p: 3, display: 'inline-block' }} elevation={3}>
-          <CheckoutForm id="cs_9zeD2yCgPXT9Vit9bab2vVC3V7DFjHiKvyoLzVTVzAf4XSU2oLWY67vKy7" mode="inline" />
-        </Paper>
-      </PaymentProvider>
-    );
-  }
-
-  if (params.get('type') === 'link') {
-    return (
-      <PaymentProvider session={session} connect={connectApi}>
-        <Typography variant="h4" gutterBottom>
-          Checkout with payment link
-        </Typography>
-        <Paper sx={{ p: 3, display: 'inline-block' }} elevation={3}>
-          <CheckoutForm id="plink_oB1I6FNeHKSkuq81fhJy0vIZ" mode="inline" />
-        </Paper>
-      </PaymentProvider>
-    );
-  }
-
-  if (params.get('type') === 'table') {
-    return (
-      <PaymentProvider session={session} connect={connectApi}>
-        <Typography variant="h4" gutterBottom>
-          Checkout with pricing table
-        </Typography>
-        <Paper sx={{ p: 3, display: 'inline-block' }} elevation={3}>
-          <CheckoutTable id="prctbl_kOsaIiPrsHAwwALaKgy17mIl" mode="inline" />
-        </Paper>
-      </PaymentProvider>
-    );
-  }
-
-  return null;
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+
+function App() {
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm 
+        id="plink_xxx"
+        mode="inline"
+        showCheckoutSummary={true}
+        onChange={(state) => console.log(state)}
+      />
+    </PaymentProvider>
+  );
 }
+```
+
+## Component Usage
+
+### Core Components
+
+```tsx
+import { CheckoutForm, CheckoutTable, CheckoutDonate, PaymentProvider } from '@blocklet/payment-react';
+
+// Checkout with session
+<CheckoutForm 
+  id="cs_xxx"
+  mode="inline"
+  showCheckoutSummary={true}
+  onChange={(state) => console.log(state)}
+/>
+
+// Checkout with payment link
+<CheckoutForm 
+  id="plink_xxx"
+  mode="inline"
+/>
 
+// Pricing table
+<CheckoutTable 
+  id="prctbl_xxx"
+  mode="inline"
+/>
+
+// Donation form
+<CheckoutDonate
+  mode="inline"
+  settings={{
+    target: 'donation-target',
+    title: 'Support Us',
+    description: 'Help us continue our work',
+    beneficiaries: [{
+      address: 'wallet_address',
+      share: '100'
+    }],
+    amount: {
+      minimum: '0.01',
+      maximum: '1',
+      custom: true
+    }
+  }}
+/>
 ```
 
-## I18n
+### Form Components
 
 ```tsx
-import { createTranslator, translations as extraTranslations } from '@blocklet/payment-react';
-import merge from 'lodash/merge';
+import { 
+  FormInput,
+  PhoneInput,
+  AddressForm,
+  CurrencySelector,
+  CountrySelect
+} from '@blocklet/payment-react';
 
-import en from './en';
-import zh from './zh';
+// Phone input with validation
+<PhoneInput
+  name="phone"
+  countryFieldName="billing_address.country"
+/>
 
-// eslint-disable-next-line import/prefer-default-export
-export const translations = merge({ zh, en }, extraTranslations);
+// Address form
+<AddressForm
+  mode="required"
+  stripe={false}
+  sx={{}}
+/>
+
+// Currency selector
+<CurrencySelector
+  value={0}
+  onChange={(index) => {}}
+  currencies={[
+    {
+      id: 'currency_id',
+      symbol: '$',
+      logo: 'currency_logo_url',
+      name: 'USD',
+      method: { name: 'Payment Method' }
+    }
+  ]}
+/>
+
+// Country select
+<CountrySelect
+  value="us"
+  onChange={(value: CountryIso2) => {}}
+  name="country"
+  sx={{}}
+/>
+```
+
+### Display Components
+
+```tsx
+import {
+  PricingItem,
+  TruncatedText,
+  TxGas,
+  TxLink,
+  ProductSkeleton,
+} from '@blocklet/payment-react';
+
+// Display pricing information
+<PricingItem 
+  productId="prod_xxx"
+  quantity={1}
+  priceId="price_xxx"
+>
+  {(pricing, product) => (
+    <div>
+      <div>Total: {pricing.totalPrice}</div>
+      <div>Product: {product?.name}</div>
+    </div>
+  )}
+</PricingItem>
+
+// Display transaction gas fee
+<TxGas 
+  details={paymentDetails}
+  method={paymentMethod}
+/>
+
+// Display transaction link
+<TxLink 
+  details={paymentDetails}
+  method={paymentMethod}
+  mode="dashboard"
+  align="left"
+/>
+
+// Loading skeleton
+<ProductSkeleton />
+
+// Truncate long text
+<TruncatedText 
+  text="Very long text..." 
+  maxLength={20} 
+/>
 ```
 
-## Updates
+### Donation Components
+
+```tsx
+import { CheckoutDonate } from '@blocklet/payment-react';
+
+// Basic usage
+<CheckoutDonate
+  mode="default"  // 'default' | 'inline' | 'custom'
+  settings={{
+    target: 'donation-target',
+    title: 'Support Us',
+    description: 'Help us continue our work',
+    beneficiaries: [{
+      address: 'wallet_address',
+      share: '100'
+    }],
+    amount: {
+      minimum: '0.01',
+      maximum: '100',
+      custom: true
+    },
+    appearance: {
+      button: {
+        text: 'Donate Now',
+        icon: <FavoriteIcon />,
+        size: 'large',
+        color: 'primary',
+        variant: 'contained'
+      },
+      history: {
+        variant: 'avatar'  // 'avatar' | 'table'
+      }
+    }
+  }}
+/>
+
+// Custom render mode
+<CheckoutDonate
+  mode="custom"
+  settings={{
+    target: 'custom-donation',
+    // ... other settings
+  }}
+>
+  {(openDonate, totalAmount, supporters) => (
+    <div>
+      <button onClick={openDonate}>
+        Support Us
+      </button>
+      <div>Total Donations: {totalAmount}</div>
+      <div>Supporters: {supporters.supporters.length}</div>
+      {supporters.supporters.map(supporter => (
+        <div key={supporter.id}>
+          <img src={supporter.customer?.avatar} alt={supporter.customer?.name} />
+          <span>{supporter.customer?.name}</span>
+          <span>{formatAmount(supporter.amount_total, supporters.currency.decimal)} {supporters.currency.symbol}</span>
+        </div>
+      ))}
+    </div>
+  )}
+</CheckoutDonate>
+```
+
+### Lazy Loading Components
+
+The SDK provides `createLazyComponent` for optimizing bundle size by loading components and their dependencies on demand:
+
+```tsx
+import { createLazyComponent } from '@blocklet/payment-react';
+
+// 1. Create lazy component with dependencies
+const LazyComponent = createLazyComponent(async () => {
+  // Load dependencies in parallel
+  const [dep1, dep2] = await Promise.all([
+    import('heavy-dependency-1'),
+    import('heavy-dependency-2')
+  ]);
+
+  // Store dependencies for reuse
+  const dependencies = {
+    Component1: dep1.Component1,
+    Component2: dep1.Component2,
+    useHook1: dep2.useHook1,
+    useHook2: dep2.useHook2,
+  };
+
+  // Make dependencies available to child components
+  globalThis.__DEPENDENCIES__ = dependencies;
+
+  // Load and return the actual component that uses these dependencies
+  const { default: Component } = await import('./MyComponent');
+  return Component;
+});
+
+// 2. Use dependencies in your component
+// Access loaded dependencies
+const { 
+  Component1, 
+  Component2,
+  useHook1,
+  useHook2 
+} = globalThis.__DEPENDENCIES__;
+function MyComponent(props) {
+  // Use hooks from dependencies
+  const hook1Result = useHook1();
+  const hook2Result = useHook2();
+
+  return (
+    <div>
+      <Component1 {...hook1Result} />
+      <Component2 {...hook2Result} />
+    </div>
+  );
+}
+
+// 3. Use the lazy component
+function App() {
+  return (
+    <LazyComponent 
+      prop1="value1"
+      prop2="value2"
+      onEvent={() => {}}
+    />
+  );
+}
+```
+
+Key features:
+- 🚀 Loads dependencies on demand
+- 📦 Reduces initial bundle size
+- 🌐 Provides global access to loaded dependencies
+- ⚡️ Supports parallel loading
+- 🔄 Handles async initialization
+- ❌ Built-in error handling
+
+## Theme Customization
 
-#### theme
 Since version 1.14.22, the component includes a built-in theme provider. If you need to modify the styles of internal components, you need to pass the `theme` property to override or inherit the external theme.
 
-| option |description |
+| option | description |
 | --- | --- |
 | default [default value] | wrapped with built-in PaymentThemeProvider |
 | inherit | use the parent component's themeProvider |
@@ -84,12 +318,12 @@ Since version 1.14.22, the component includes a built-in theme provider. If you
 export type PaymentThemeOptions = ThemeOptions & {
   sx?: SxProps;
 };
-
 ```
- ```js
+
+```tsx
 // 1. use themeOptions
- <CheckoutForm
-  id="plink_oB1I6FNeHKSkuq81fhJy0vIZ"
+<CheckoutForm
+  id="plink_xxx"
   onChange={console.info}
   theme={{
     components: {
@@ -110,8 +344,8 @@ export type PaymentThemeOptions = ThemeOptions & {
 
 // 2. use theme sx
 <CheckoutForm
-  id="plink_oB1I6FNeHKSkuq81fhJy0vIZ"
-  mode="inline-minimal"
+  id="plink_xxx"
+  showCheckoutSummary={false}
   onChange={console.info}
   theme={{
     sx: {
@@ -127,21 +361,84 @@ export type PaymentThemeOptions = ThemeOptions & {
 />
 ```
 
-#### showCheckoutSummary
+## I18n Support
 
-Since version 1.14.23, if you need to hide the product column, we recommend using `showCheckoutSummary=false` instead of `mode=inline-minimal`. We aim for better semantics.
-```js
-// bad
+```tsx
+import { createTranslator, translations as extraTranslations } from '@blocklet/payment-react';
+import merge from 'lodash/merge';
+
+import en from './en';
+import zh from './zh';
+
+export const translations = merge({ zh, en }, extraTranslations);
+```
+
+## Recent Updates
+
+### v1.14.23
+We recommend using `showCheckoutSummary={false}` instead of `mode=inline-minimal` for better semantics:
+
+```tsx
+// Recommended
 <CheckoutForm
-  id="plink_oB1I6FNeHKSkuq81fhJy0vIZ"
-  mode="inline-minimal"
+  id="plink_xxx"
+  showCheckoutSummary={false}
   onChange={console.info}
 />
 
-// good
+// Not recommended
 <CheckoutForm
-  id="plink_oB1I6FNeHKSkuq81fhJy0vIZ"
-  showCheckoutSummary={false}
+  id="plink_xxx"
+  mode="inline-minimal"
   onChange={console.info}
 />
-```
+```
+
+### Status & Utility Components
+```tsx
+import { 
+  Status,
+  Livemode,
+  Switch,
+  Link,
+  Amount
+} from '@blocklet/payment-react';
+
+// Status indicator for payment states
+<Status 
+  label="active"
+  color="success"
+  size="small"
+  sx={{ margin: 1 }}
+/>
+
+// Live/Test mode indicator
+<Livemode livemode={false} />
+
+// Custom switch button
+<Switch
+  checked={true}
+  onChange={(checked) => console.log('Switched:', checked)}
+  size="small"
+  color="primary"
+/>
+
+// Safe navigation link
+<Link
+  href="https://example.com"
+  confirmBeforeNavigate={true}
+  confirmMessage="Are you sure to leave?"
+  target="_blank"
+/>
+
+// Amount display with formatting
+<Amount
+  value={1000}
+  currency={{
+    symbol: '$',
+    decimal: 2
+  }}
+  variant="body1"
+  color="primary"
+/>
+```

package/es/components/pricing-table.js

@@ -368,7 +368,8 @@ export default function PricingTable({ table, alignItems, interval, mode, onSele
                                     display: "flex",
                                     alignItems: "baseline",
                                     gap: "4px",
-                                    flexWrap: "wrap"
+                                    flexWrap: "wrap",
+                                    lineHeight: "normal"
                                   },
                                   children: [
                                     amount,

package/es/libs/util.js

@@ -881,7 +881,8 @@ export function getInvoiceDescriptionAndReason(invoice, locale = "en") {
     "Stake for subscription payment change": t("payment.invoice.reason.stakeForChangePayment", locale),
     "Stake for subscription": t("payment.invoice.reason.staking", locale),
     "Return Subscription staking": t("payment.invoice.reason.returnStake", locale),
-    "Recharge for subscription": t("payment.invoice.reason.rechargeForSubscription", locale)
+    "Recharge for subscription": t("payment.invoice.reason.rechargeForSubscription", locale),
+    "Add funds for subscription": t("payment.invoice.reason.rechargeForSubscription", locale)
   };
   return {
     description: descMap[description] || description,

package/es/locales/en.js

@@ -313,8 +313,8 @@ export default flat({
         returnStake: "Return stake",
         stakeForChangePlan: "Subscription plan update",
         stakeForChangePayment: "Subscription payment method update",
-        recharge: "Recharge",
-        rechargeForSubscription: "Subscription recharge"
+        recharge: "Add funds",
+        rechargeForSubscription: "Add funds for subscription"
       }
     }
   },

package/lib/components/pricing-table.js

@@ -385,7 +385,8 @@ function PricingTable({
                     display: "flex",
                     alignItems: "baseline",
                     gap: "4px",
-                    flexWrap: "wrap"
+                    flexWrap: "wrap",
+                    lineHeight: "normal"
                   },
                   children: [amount, unit ? /* @__PURE__ */(0, _jsxRuntime.jsxs)(_material.Typography, {
                     sx: {

package/lib/libs/util.js

@@ -1064,7 +1064,8 @@ function getInvoiceDescriptionAndReason(invoice, locale = "en") {
     "Stake for subscription payment change": (0, _locales.t)("payment.invoice.reason.stakeForChangePayment", locale),
     "Stake for subscription": (0, _locales.t)("payment.invoice.reason.staking", locale),
     "Return Subscription staking": (0, _locales.t)("payment.invoice.reason.returnStake", locale),
-    "Recharge for subscription": (0, _locales.t)("payment.invoice.reason.rechargeForSubscription", locale)
+    "Recharge for subscription": (0, _locales.t)("payment.invoice.reason.rechargeForSubscription", locale),
+    "Add funds for subscription": (0, _locales.t)("payment.invoice.reason.rechargeForSubscription", locale)
   };
   return {
     description: descMap[description] || description,

package/lib/locales/en.js

@@ -320,8 +320,8 @@ module.exports = (0, _flat.default)({
         returnStake: "Return stake",
         stakeForChangePlan: "Subscription plan update",
         stakeForChangePayment: "Subscription payment method update",
-        recharge: "Recharge",
-        rechargeForSubscription: "Subscription recharge"
+        recharge: "Add funds",
+        rechargeForSubscription: "Add funds for subscription"
       }
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocklet/payment-react",
-  "version": "1.16.0",
+  "version": "1.16.2",
   "description": "Reusable react components for payment kit v2",
   "keywords": [
     "react",
@@ -53,15 +53,15 @@
     }
   },
   "dependencies": {
-    "@arcblock/did-connect": "^2.10.65",
-    "@arcblock/ux": "^2.10.65",
-    "@arcblock/ws": "^1.18.139",
-    "@blocklet/ui-react": "^2.10.65",
+    "@arcblock/did-connect": "^2.10.67",
+    "@arcblock/ux": "^2.10.67",
+    "@arcblock/ws": "^1.18.147",
+    "@blocklet/ui-react": "^2.10.67",
     "@mui/icons-material": "^5.16.6",
     "@mui/lab": "^5.0.0-alpha.173",
     "@mui/material": "^5.16.6",
     "@mui/system": "^5.16.6",
-    "@ocap/util": "^1.18.139",
+    "@ocap/util": "^1.18.147",
     "@stripe/react-stripe-js": "^2.7.3",
     "@stripe/stripe-js": "^2.4.0",
     "@vitejs/plugin-legacy": "^5.4.1",
@@ -92,7 +92,7 @@
     "@babel/core": "^7.25.2",
     "@babel/preset-env": "^7.25.2",
     "@babel/preset-react": "^7.24.7",
-    "@blocklet/payment-types": "1.16.0",
+    "@blocklet/payment-types": "1.16.2",
     "@storybook/addon-essentials": "^7.6.20",
     "@storybook/addon-interactions": "^7.6.20",
     "@storybook/addon-links": "^7.6.20",
@@ -122,5 +122,5 @@
     "vite-plugin-babel": "^1.2.0",
     "vite-plugin-node-polyfills": "^0.21.0"
   },
-  "gitHead": "8d3dd981076bd6ace838f221a2171228456cb1f9"
+  "gitHead": "63c0ef382409afb79f595f82ea5e9bb9f264b844"
 }

package/src/components/pricing-table.tsx

@@ -401,6 +401,7 @@ export default function PricingTable({ table, alignItems, interval, mode, onSele
                         alignItems: 'baseline',
                         gap: '4px',
                         flexWrap: 'wrap',
+                        lineHeight: 'normal',
                       }}>
                       {amount}
                       {unit ? (

package/src/libs/util.ts

@@ -1140,6 +1140,7 @@ export function getInvoiceDescriptionAndReason(invoice: TInvoiceExpanded, locale
     'Stake for subscription': t('payment.invoice.reason.staking', locale),
     'Return Subscription staking': t('payment.invoice.reason.returnStake', locale),
     'Recharge for subscription': t('payment.invoice.reason.rechargeForSubscription', locale),
+    'Add funds for subscription': t('payment.invoice.reason.rechargeForSubscription', locale),
   };
 
   return {

package/src/locales/en.tsx

@@ -326,8 +326,8 @@ export default flat({
         returnStake: 'Return stake',
         stakeForChangePlan: 'Subscription plan update',
         stakeForChangePayment: 'Subscription payment method update',
-        recharge: 'Recharge',
-        rechargeForSubscription: 'Subscription recharge',
+        recharge: 'Add funds',
+        rechargeForSubscription: 'Add funds for subscription',
       },
     },
   },