@blocklet/payment-react 1.19.23 → 1.20.0

package/docs/guides-utilities.md

@@ -0,0 +1,235 @@
+# Utilities
+
+The `@blocklet/payment-react` library exports several utility functions and classes to simplify common tasks in your application, such as client-side caching, date formatting, and internationalization. These tools are designed to work seamlessly with the library's components and the underlying payment infrastructure.
+
+## API Client
+
+The library exports a pre-configured Axios instance for making API requests to your payment backend. It automatically handles base URLs and authentication when used within the `PaymentProvider` context. For more details on setting up the provider, see the [PaymentProvider documentation](./providers-payment-provider.md).
+
+```tsx
+import { api } from '@blocklet/payment-react';
+
+// Basic GET request
+const response = await api.get('/api/payments');
+
+// POST request with a body
+const data = await api.post('/api/checkout', { amount: 100 });
+
+// Request with query parameters
+const results = await api.get('/api/invoices', {
+  params: { status: 'paid' }
+});
+
+// Request with custom configuration
+const config = {
+  headers: { 'Custom-Header': 'value' }
+};
+const response = await api.put('/api/subscription', data, config);
+```
+
+## CachedRequest
+
+The `CachedRequest` class offers a straightforward way to implement client-side caching, reducing redundant network calls and improving your application's responsiveness. It supports multiple caching strategies and time-to-live (TTL) configurations.
+
+```d2
+direction: down
+
+fetch: "Call priceRequest.fetch()"
+cache_check: "Is data in cache and not expired?"
+
+fetch -> cache_check
+
+subgraph "Cache Hit" {
+  direction: down
+  style.stroke: "#4CAF50"
+  return_cached: "Return cached data"
+}
+
+subgraph "Cache Miss" {
+  direction: down
+  style.stroke: "#F44336"
+  api_call: "Execute api.get('/api/prices')"
+  store_cache: "Store response in cache with timestamp"
+  return_fresh: "Return fresh data"
+  api_call -> store_cache -> return_fresh
+}
+
+cache_check -> return_cached: Yes
+cache_check -> api_call: No
+```
+
+### Usage
+
+To use it, create an instance of `CachedRequest` with a unique key, a data-fetching function, and optional configuration.
+
+```tsx
+import { CachedRequest, api } from '@blocklet/payment-react';
+
+// Create a cached request instance
+const priceRequest = new CachedRequest(
+  'product-prices',
+  () => api.get('/api/prices'),
+  {
+    strategy: 'session',  // 'session' | 'local' | 'memory'
+    ttl: 5 * 60 * 1000   // Cache for 5 minutes
+  }
+);
+
+// Use the cached request
+async function fetchPrices() {
+  // This will use the cache if available and not expired
+  const prices = await priceRequest.fetch();
+
+  // To bypass the cache and force a network request
+  const freshPrices = await priceRequest.fetch(true);
+
+  return prices;
+}
+```
+
+### Configuration Options
+
+| Option | Type | Description |
+|---|---|---|
+| `strategy` | `'session'` \| `'local'` \| `'memory'` | The caching strategy to use. `session` uses `sessionStorage`, `local` uses `localStorage`, and `memory` uses a global in-memory cache. Defaults to `'session'`. |
+| `ttl` | `number` | Time-to-live in milliseconds. After this duration, the cached data is considered expired. Defaults to `0` (no expiration). |
+
+## Date Handling with dayjs
+
+The library exports a pre-configured `dayjs` instance with useful plugins already enabled, including `relativeTime`, `localizedFormat`, `duration`, `utc`, and `timezone`. This ensures consistent date and time handling across your application.
+
+```tsx
+import { dayjs } from '@blocklet/payment-react';
+
+// Format the current date
+const formattedDate = dayjs().format('YYYY-MM-DD');
+
+// Parse a timestamp and get its Unix value
+const timestamp = 1672531200000;
+const dateObject = dayjs(timestamp);
+const unixValue = dateObject.unix();
+
+// Display relative time
+const fiveMinutesAgo = dayjs().subtract(5, 'minute');
+const relativeString = dayjs().from(fiveMinutesAgo);
+```
+
+## Formatting Utilities
+
+A collection of functions to format data for display, from prices and statuses to plain text.
+
+### Price and Amount Formatting
+
+These functions help display monetary values and quantities correctly according to currency decimals and locale conventions.
+
+- `formatPrice(price, currency, unit_label, quantity)`: Formats a full price object into a human-readable string, including recurring intervals (e.g., "$10.00 / month").
+- `formatAmount(amount, decimals)`: Formats a raw amount string based on the currency's decimal places.
+- `formatBNStr(str, decimals, precision)`: Formats a BigNumber string into a readable number, handling large values and token conversions.
+
+```tsx
+import { formatPrice, formatAmount } from '@blocklet/payment-react';
+
+// Example price and currency objects (simplified)
+const price = { type: 'recurring', recurring: { interval: 'month', interval_count: 1 }, unit_amount: '1000' };
+const currency = { symbol: '$', decimal: 2 };
+
+const displayPrice = formatPrice(price, currency);
+// Result: "10.00 $ per month"
+
+const displayAmount = formatAmount('12345', 2);
+// Result: "123.45"
+```
+
+### Status Colors
+
+Several utility functions map resource statuses to semantic colors (`success`, `warning`, `error`, `primary`, `default`) for consistent UI indicators in components like `<Status />`.
+
+| Function | Status Examples | Color |
+|---|---|---|
+| `getSubscriptionStatusColor` | `active`, `trialing` | `success`, `primary` |
+| `getInvoiceStatusColor` | `paid`, `open`, `uncollectible` | `success`, `secondary`, `warning` |
+| `getPaymentIntentStatusColor` | `succeeded`, `requires_action` | `success`, `warning` |
+| `getRefundStatusColor` | `succeeded`, `pending` | `success`, `default` |
+
+### Text Utilities
+
+- `truncateText(text, maxLength, useWidth)`: Truncates a string to a specified length, adding an ellipsis. The `useWidth` option calculates length based on character width for better CJK character handling.
+
+## Internationalization (i18n)
+
+For applications targeting a global audience, the library includes utilities to manage translations.
+
+### `createTranslator`
+
+You can create your own translator instance with custom language packs.
+
+```tsx
+import { createTranslator } from '@blocklet/payment-react';
+
+const myTranslations = {
+  en: {
+    checkout: { title: 'Complete Payment' }
+  },
+  zh: {
+    checkout: { title: '完成支付' }
+  }
+};
+
+const translator = createTranslator({ fallbackLocale: 'en' }, myTranslations);
+
+console.log(translator('checkout.title', 'zh')); // Outputs: '完成支付'
+```
+
+### Merging with Library Translations
+
+To leverage the built-in translations for payment components, you can merge them with your application's translation files.
+
+```tsx
+import { translations as paymentTranslations } from '@blocklet/payment-react';
+import merge from 'lodash/merge';
+
+import en from './en'; // Your app's English translations
+import zh from './zh'; // Your app's Chinese translations
+
+export const translations = merge(
+  {
+    zh,
+    en,
+  },
+  paymentTranslations
+);
+```
+
+## Lazy Loading Components
+
+To optimize your application's bundle size, you can use the `createLazyComponent` utility to dynamically load components only when they are needed.
+
+```tsx
+import { createLazyComponent } from '@blocklet/payment-react';
+
+const LazyLoadedComponent = createLazyComponent(async () => {
+  // Dynamically import the component and its dependencies
+  const [{ Component }, { useHook }] = await Promise.all([
+    import('./Component'),
+    import('./hooks')
+  ]);
+
+  // Make dependencies available if needed
+  globalThis.__DEPENDENCIES__ = { useHook };
+
+  return Component;
+});
+
+function App() {
+  return (
+    <div>
+      {/* This component will be loaded on demand */}
+      <LazyLoadedComponent />
+    </div>
+  );
+}
+```
+
+---
+
+These utilities provide robust solutions for common development challenges. To learn about the custom React hooks for handling side effects and state, proceed to the [Hooks](./hooks.md) guide.

package/docs/guides.md

@@ -0,0 +1,95 @@
+# Guides
+
+Welcome to the guides section. While the Components documentation covers individual UI pieces, these guides focus on broader topics that span the entire library. Here, you'll learn about advanced subjects like customizing the appearance of your payment flows, using powerful utility functions, and implementing patterns to create a robust and polished user experience.
+
+These guides are designed for developers looking to move beyond basic integration and fully leverage the capabilities of `@blocklet/payment-react`.
+
+<x-cards>
+  <x-card data-title="Theming" data-icon="lucide:palette" data-href="/guides/theming">
+    Learn how to customize the look and feel of payment components to match your application's branding using Material-UI themes.
+  </x-card>
+  <x-card data-title="Utilities" data-icon="lucide:wrench" data-href="/guides/utilities">
+    Explore a suite of helper functions for common tasks like cached data fetching, date formatting, and internationalization.
+  </x-card>
+</x-cards>
+
+---
+
+## Customizing Appearance
+
+The library is built on Material-UI and exposes a flexible theming system. You can provide a custom theme configuration to adjust everything from colors and typography to the shape of buttons and inputs. For a comprehensive overview, see the full [Theming Guide](./guides-theming.md).
+
+For example, you can change the primary button color by passing a `theme` object to a component. Note that components requiring session context must be wrapped in `PaymentProvider`.
+
+```tsx
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+// useSessionContext is a hook from your app's session management setup.
+import { useSessionContext } from '../hooks/session';
+
+function MyCheckoutPage() {
+  const { session, connectApi } = useSessionContext();
+
+  // For a complete guide on setting up PaymentProvider and session context,
+  // please refer to the PaymentProvider documentation.
+  if (!session) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm
+        id="plink_xxx"
+        theme={{
+          components: {
+            MuiButton: {
+              styleOverrides: {
+                containedPrimary: {
+                  backgroundColor: '#1DC1C7',
+                  color: '#fff',
+                  '&:hover': {
+                    backgroundColor: 'rgb(20, 135, 139)',
+                  },
+                },
+              },
+            },
+          },
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+## Simplifying Logic with Utilities
+
+Beyond components, `@blocklet/payment-react` exports a suite of utility functions and classes to handle common tasks. The `CachedRequest` class, for instance, provides an easy way to cache API responses, reducing network load and improving performance. Discover more tools in our [Utilities Guide](./guides-utilities.md).
+
+```tsx
+import { CachedRequest, api } from '@blocklet/payment-react';
+
+// Create a cached request that fetches prices and caches them for 5 minutes
+const priceRequest = new CachedRequest(
+  'product-prices',
+  () => api.get('/api/prices'),
+  {
+    strategy: 'session',  // 'session' | 'local' | 'memory'
+    ttl: 5 * 60 * 1000   // 5 minutes
+  }
+);
+
+async function fetchPrices() {
+  // Will use cache if available and not expired
+  const prices = await priceRequest.fetch();
+  
+  // Force a refresh from the network
+  const freshPrices = await priceRequest.fetch(true);
+  
+  return prices;
+}
+```
+
+---
+
+## Next Steps
+
+After mastering these advanced topics, proceed to the [Hooks](./hooks.md) documentation to learn about handling real-time events and responsive design.

package/docs/hooks-use-mobile.md

@@ -0,0 +1,70 @@
+# useMobile
+
+The `useMobile` hook is a convenient utility for creating responsive layouts in your application. It helps determine if the current viewport width is considered 'mobile' based on standard Material-UI breakpoints.
+
+This hook simplifies responsive logic by abstracting away the underlying `useTheme` and `useMediaQuery` calls from Material-UI.
+
+## Basic Usage
+
+Import the hook and use it within your component to get a boolean value indicating if the screen is mobile-sized, along with the corresponding pixel width for that breakpoint.
+
+```tsx
+import { useMobile } from '@blocklet/payment-react';
+import Typography from '@mui/material/Typography';
+
+function ResponsiveComponent() {
+  const { isMobile } = useMobile();
+
+  return (
+    <Typography variant="h5">
+      {isMobile ? 'This is the mobile view.' : 'This is the desktop view.'}
+    </Typography>
+  );
+}
+```
+
+In this example, the component will render different text depending on whether the screen width is below the default 'md' (medium) breakpoint.
+
+## Parameters
+
+The `useMobile` hook accepts an optional parameter to customize the breakpoint used for mobile detection.
+
+| Name          | Type                                       | Default | Description                                                                                                   |
+|---------------|--------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------|
+| `mobilePoint` | `'xs'` \| `'sm'` \| `'md'` \| `'lg'` \| `'xl'` | `'md'`  | The Material-UI breakpoint to use as the threshold. The hook will return `true` for screen sizes at or below this point. |
+
+## Return Value
+
+The hook returns an object with two properties:
+
+| Key          | Type      | Description                                                                                             |
+|--------------|-----------|---------------------------------------------------------------------------------------------------------|
+| `isMobile`   | `boolean` | `true` if the screen width is at or below the specified `mobilePoint`, otherwise `false`.               |
+| `mobileSize` | `string`  | A string representing the pixel width of the `mobilePoint` breakpoint (e.g., `'900px'` for the `'md'` breakpoint). |
+
+## Example with Custom Breakpoint
+
+You can specify a different breakpoint if your application's design requires a different threshold for mobile view.
+
+```tsx
+import { useMobile } from '@blocklet/payment-react';
+import Box from '@mui/material/Box';
+
+function CustomBreakpointComponent() {
+  // Consider 'sm' and below as mobile
+  const { isMobile, mobileSize } = useMobile('sm');
+
+  return (
+    <Box sx={{ p: 2, border: '1px solid grey' }}>
+      <p>The mobile breakpoint is set to {mobileSize}.</p>
+      {isMobile ? (
+        <p>This layout is optimized for smaller screens.</p>
+      ) : (
+        <p>This layout is for tablets and desktops.</p>
+      )}
+    </Box>
+  );
+}
+```
+
+This component adjusts its responsive behavior based on the 'sm' (small) breakpoint, providing more granular control over your UI.

package/docs/hooks-use-subscription.md

@@ -0,0 +1,129 @@
+# useSubscription
+
+The `useSubscription` hook provides a straightforward way to subscribe to real-time events from the payment service. It manages the WebSocket connection lifecycle, allowing your components to react instantly to backend events like `invoice.paid` or `subscription.updated`.
+
+This is essential for creating dynamic user experiences where the UI needs to reflect changes without requiring manual refreshes.
+
+## How It Works
+
+The hook abstracts the complexity of managing a WebSocket connection. When your component mounts, `useSubscription` establishes a connection to the relay service, subscribes to the specified channel, and returns a subscription object. This object can then be used to listen for incoming events. The hook also handles cleanup, disconnecting and unsubscribing when the component unmounts.
+
+```d2
+shape: sequence_diagram
+
+Component: "Your React Component"
+Hook: "useSubscription Hook"
+WsClient: "WebSocket Client"
+Relay: "Relay Service"
+
+Component -> Hook: "Renders and calls useSubscription(\"invoice_xyz\")"
+Hook -> WsClient: "Establishes WebSocket connection if not connected"
+WsClient -> Relay: "Connects to service endpoint"
+Hook -> WsClient: "Subscribes to formatted channel (e.g., relay:appId:invoice_xyz)"
+WsClient -> Relay: "Sends subscription request"
+Relay -> WsClient: "Confirms subscription"
+Hook -> Component: "Returns subscription object"
+
+Component -> Component: "Attaches event listener (e.g., subscription.on('update', ...))"
+
+Relay -> WsClient: "Pushes 'update' event with data"
+WsClient -> Hook: "Forwards event to the subscription"
+Hook -> Component: "Triggers the attached event listener"
+Component -> Component: "Updates state (e.g., setStatus('Paid'))"
+```
+
+## Usage
+
+To use the hook, simply pass the channel you wish to subscribe to. The underlying implementation requires that the channel name does not contain special characters like `/`, `.`, or `:`, as this will prevent the client from receiving events.
+
+### Parameters
+
+| Name      | Type     | Description                                                                                                                                                                                             |
+| :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `channel` | `string` | **Required**. A unique identifier for the subscription channel. It must not contain special characters like `/`, `.`, or `:`. The hook prefixes this with the application ID to create the final channel name (e.g., `relay:appId:channel`).       |
+
+### Return Value
+
+The hook returns a `subscription` object, which is an instance of the WebSocket client's subscription handler. You can attach event listeners to this object using its `.on(eventName, callback)` method.
+
+## Example
+
+Here is an example of a component that displays the status of an invoice. It uses `useSubscription` to listen for real-time updates and changes the status from "Pending" to "Paid" when an `invoice.paid` event is received.
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { PaymentProvider, useSubscription } from '@blocklet/payment-react';
+
+// Assume this hook is defined in your application to provide session context.
+// See the PaymentProvider documentation for an example implementation.
+import { useSessionContext } from './session-context';
+
+interface InvoiceStatusProps {
+  invoiceId: string;
+  initialStatus: 'pending' | 'paid' | 'failed';
+}
+
+function InvoiceStatus({ invoiceId, initialStatus }: InvoiceStatusProps) {
+  const [status, setStatus] = useState(initialStatus);
+  
+  // The channel should be a simple string.
+  const subscription = useSubscription(invoiceId);
+
+  useEffect(() => {
+    // Ensure the subscription object is available before attaching listeners.
+    if (subscription) {
+      const handleInvoiceUpdate = (event: { status: string }) => {
+        console.log('Received event:', event);
+        if (event.status === 'paid') {
+          setStatus('paid');
+        }
+      };
+
+      // Listen for a specific event name.
+      // The actual event name depends on your backend implementation.
+      subscription.on('invoice.paid', handleInvoiceUpdate);
+
+      // Cleanup function to remove the listener when the component
+      // unmounts or the subscription object changes.
+      return () => {
+        subscription.off('invoice.paid', handleInvoiceUpdate);
+      };
+    }
+  }, [subscription]); // Re-run effect if the subscription object changes.
+
+  return (
+    <div>
+      <h2>Invoice Status</h2>
+      <p>Invoice ID: {invoiceId}</p>
+      <p>Status: <strong>{status.toUpperCase()}</strong></p>
+    </div>
+  );
+}
+
+// Example of how to use the InvoiceStatus component within an application.
+function App() {
+  const { session, connectApi } = useSessionContext();
+
+  // Render the component only after the session is loaded.
+  if (!session) {
+    return <div>Loading session...</div>;
+  }
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <InvoiceStatus invoiceId="invoice_12345" initialStatus="pending" />
+    </PaymentProvider>
+  );
+}
+
+export default App;
+```
+
+In this example:
+1. The `App` component calls `useSessionContext()` to retrieve the user `session` and `connectApi` client.
+2. It renders the `PaymentProvider`, which provides the necessary context to its children. For details on setting up your session context, please refer to the [PaymentProvider](./providers-payment-provider.md) documentation.
+3. The `InvoiceStatus` component subscribes to a channel named after the `invoiceId`.
+4. An effect is set up to listen for changes to the `subscription` object.
+5. Once the `subscription` object is available, an event handler `handleInvoiceUpdate` is attached to the `invoice.paid` event.
+6. When a matching event is received from the server, the handler updates the component's state, and the UI re-renders to show the "PAID" status.
+7. The `useEffect` cleanup function ensures the event listener is removed to prevent memory leaks.

package/docs/hooks.md

@@ -0,0 +1,84 @@
+# Hooks
+
+The `@blocklet/payment-react` library includes custom React hooks to manage specific functionalities and side effects within your application. These hooks abstract away complex logic, making it easier to handle real-time events and create responsive user interfaces.
+
+This section provides an overview of the available hooks. For detailed usage and examples, refer to the specific hook's documentation.
+
+---
+
+## useSubscription
+
+The `useSubscription` hook establishes a WebSocket connection to listen for real-time events from the payment service. It is essential for scenarios where you need to react to asynchronous updates, such as a payment being successfully processed or an invoice status changing.
+
+**When to Use:**
+- When you need to update the UI in real-time based on backend payment events.
+- To listen for `invoice.paid`, `subscription.updated`, or other critical events without constant polling.
+
+**Basic Usage:**
+
+```tsx
+import { useSubscription } from '@blocklet/payment-react';
+import { useEffect } from 'react';
+
+function RealTimeInvoiceStatus({ invoiceId }) {
+  // The channel's value cannot contain separators like /, ., :
+  const channel = `invoice_${invoiceId}`;
+  const subscription = useSubscription(channel);
+
+  useEffect(() => {
+    if (subscription) {
+      subscription.on('invoice.paid', (data) => {
+        console.log('Invoice paid!', data);
+        // Update UI to show paid status
+      });
+    }
+  }, [subscription]);
+
+  return <div>Listening for updates on invoice {invoiceId}...</div>;
+}
+```
+
+➡️ **[Learn more about `useSubscription`](./hooks-use-subscription.md)**
+
+---
+
+## useMobile
+
+The `useMobile` hook is a simple utility for detecting the viewport size. It helps determine if the application is being viewed on a mobile device based on Material-UI's breakpoint system, which is useful for creating responsive payment flows.
+
+**When to Use:**
+- To conditionally render different layouts for mobile and desktop views.
+- To adjust component props (e.g., `mode='inline'` vs `mode='popup'`) based on screen size.
+
+**Basic Usage:**
+
+```tsx
+import { PaymentProvider, CheckoutForm, useMobile } from '@blocklet/payment-react';
+// Import your own session context hook
+import { useSessionContext } from '../hooks/session'; 
+
+function ResponsiveCheckout() {
+  const { session, connectApi } = useSessionContext();
+  const { isMobile } = useMobile();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm
+        id="plink_xxx"
+        // Use a different mode on mobile devices
+        mode={isMobile ? 'popup' : 'inline'}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+➡️ **[Learn more about `useMobile`](./hooks-use-mobile.md)**
+
+---
+
+## Next Steps
+
+Now that you have an overview of the available hooks, you can explore the rich set of UI and business logic components to build your payment flows.
+
+➡️ **[Explore Components](./components.md)**