@blocklet/payment-react 1.20.4 → 1.20.6

package/docs/hooks-use-subscription.md

@@ -1,129 +1,112 @@
 # 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`.
+The `useSubscription` hook provides a simple way to subscribe to real-time events from the payment service using WebSockets. It handles the connection, subscription, and cleanup logic, allowing you to focus on how your application reacts to events like `invoice.paid`.
 
-This is essential for creating dynamic user experiences where the UI needs to reflect changes without requiring manual refreshes.
+This is essential for creating dynamic user experiences where the UI needs to update instantly in response to backend events without requiring the user to refresh the page.
 
 ## 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.
+The hook abstracts the complexity of managing a WebSocket connection. When a component uses `useSubscription`, it establishes a persistent connection to a relay service. It then subscribes to a specific `channel` you provide. The hook automatically namespaces the channel for you, constructing a final channel name in the format `relay:<app-id>:<your-channel>`.
+
+When the backend service publishes an event to that channel, the hook's subscription object emits the event, which your component can listen for.
 
 ```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'))"
+direction: down
+
+react-component: {
+  label: "React Component"
+  shape: rectangle
+}
+
+use-subscription-hook: {
+  label: "useSubscription Hook"
+  shape: rectangle
+}
+
+websocket-server: {
+  label: "WebSocket Server"
+  shape: rectangle
+}
+
+backend-service: {
+  label: "Backend Service"
+  shape: rectangle
+}
+
+react-component -> use-subscription-hook: "1. Call with channel ID"
+use-subscription-hook -> websocket-server: "2. Connect & Subscribe to namespaced channel"
+backend-service -> websocket-server: "3. Publish event (e.g., 'invoice.paid')"
+websocket-server -> use-subscription-hook: "4. Push event to client"
+use-subscription-hook -> react-component: "5. Emit event to listener"
+react-component -> react-component: "6. Update UI"
 ```
 
-## Usage
+## Parameters
 
-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.
+The hook takes a single string argument.
 
-### Parameters
+| Parameter | Type     | Description                                                                                                                           | Required |
+| :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------ | :------- |
+| `channel`   | `string` | A unique identifier for the event stream you want to listen to. **Important**: This string must not contain separators like `/`, `.`, or `:`. | Yes      |
 
-| 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
 
-### Return Value
+The hook returns a `subscription` object from the underlying `@arcblock/ws` client library. This object may initially be `null` while the connection is being established.
 
-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.
+Once the connection is successful, the returned object provides methods to manage event listeners:
 
-## Example
+-   `subscription.on(eventName, handler)`: Attaches an event listener.
+-   `subscription.off(eventName, handler)`: Removes an event listener.
 
-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';
+## Example Usage
 
-// 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';
+Here's an example of a component that tracks the status of an invoice in real-time. When the backend broadcasts an `invoice.paid` event on the invoice's channel, the component's UI updates automatically.
 
-interface InvoiceStatusProps {
-  invoiceId: string;
-  initialStatus: 'pending' | 'paid' | 'failed';
-}
+```tsx Real-time Invoice Status Tracker icon=logos:react
+import { useSubscription } from '@blocklet/payment-react';
+import React, { useState, useEffect } from 'react';
 
-function InvoiceStatus({ invoiceId, initialStatus }: InvoiceStatusProps) {
-  const [status, setStatus] = useState(initialStatus);
-  
-  // The channel should be a simple string.
+/**
+ * A component that displays an invoice's status and updates it in real-time
+ * when a 'invoice.paid' event is received.
+ */
+function InvoiceStatusTracker({ invoiceId }) {
+  const [status, setStatus] = useState('pending');
+  // Subscribe to a channel dedicated to this invoice
   const subscription = useSubscription(invoiceId);
 
   useEffect(() => {
-    // Ensure the subscription object is available before attaching listeners.
+    // The subscription object becomes available after the WebSocket connection is established.
     if (subscription) {
-      const handleInvoiceUpdate = (event: { status: string }) => {
-        console.log('Received event:', event);
-        if (event.status === 'paid') {
-          setStatus('paid');
-        }
+      const handlePaymentSuccess = (eventData) => {
+        console.log(`Received 'invoice.paid' event for channel ${invoiceId}:`, eventData);
+        // Update the component's state based on the event
+        setStatus('paid');
       };
 
-      // Listen for a specific event name.
-      // The actual event name depends on your backend implementation.
-      subscription.on('invoice.paid', handleInvoiceUpdate);
+      // Attach the listener for the 'invoice.paid' event
+      subscription.on('invoice.paid', handlePaymentSuccess);
 
-      // Cleanup function to remove the listener when the component
-      // unmounts or the subscription object changes.
+      // It's crucial to clean up the event listener when the component unmounts
+      // or when the subscription object changes to prevent memory leaks.
       return () => {
-        subscription.off('invoice.paid', handleInvoiceUpdate);
+        subscription.off('invoice.paid', handlePaymentSuccess);
       };
     }
-  }, [subscription]); // Re-run effect if the subscription object changes.
+    // This effect should re-run if the subscription object itself changes.
+  }, [subscription, invoiceId]);
 
   return (
     <div>
       <h2>Invoice Status</h2>
-      <p>Invoice ID: {invoiceId}</p>
+      <p>ID: {invoiceId}</p>
       <p>Status: <strong>{status.toUpperCase()}</strong></p>
+      {status === 'pending' && <p>Waiting for payment confirmation...</p>}
+      {status === 'paid' && <p>Payment confirmed! Your invoice is settled.</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.
+export default InvoiceStatusTracker;
+```

package/docs/hooks.md

@@ -1,84 +1,14 @@
 # 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)**
+The `@blocklet/payment-react` library provides a set of custom React hooks to encapsulate and simplify common logic, such as handling real-time events or adapting to different screen sizes. These hooks allow you to easily integrate advanced functionalities into your components with minimal boilerplate code.
+
+Explore the available hooks to enhance your application's interactivity and responsiveness.
+
+<x-cards>
+  <x-card data-title="useSubscription" data-icon="lucide:webhook" data-href="/hooks/use-subscription">
+    Subscribe to real-time events from the payment service, such as 'invoice.paid', to create dynamic and responsive user experiences.
+  </x-card>
+  <x-card data-title="useMobile" data-icon="lucide:smartphone" data-href="/hooks/use-mobile">
+    A utility hook for detecting if the application is being viewed on a mobile device, helping you build responsive and mobile-friendly UIs.
+  </x-card>
+</x-cards>

package/docs/overview.md

@@ -1,87 +1,80 @@
 # Overview
 
-`@blocklet/payment-react` is a React component library designed for building payment flows, subscriptions, and donation systems within blocklets. It integrates seamlessly with [Payment Kit](https://www.arcblock.io/docs/arcblock-payment-kit) to provide a comprehensive set of pre-built UI components, context providers, and utility functions that accelerate the development of payment-related features.
-
-Whether you need a simple checkout form, a complete pricing table, or a view of a customer's invoice history, `@blocklet/payment-react` offers the tools to build it efficiently.
+`@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.
 
 ## Key Features
 
 <x-cards data-columns="3">
   <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 use cases.
+    Includes a rich set of components like checkout forms, pricing tables, and donation widgets to cover common payment scenarios out of the box.
   </x-card>
   <x-card data-title="Customizable Themes" data-icon="lucide:palette">
-    Gain full control over the look and feel using Material-UI themes, ensuring consistency with your application's design.
+    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 localization capabilities to support a global user base.
+    Built-in internationalization support allows you to easily localize component text for a global audience.
   </x-card>
-  <x-card data-title="Lazy Loading" data-icon="lucide:package-minus">
-    Optimize your application's bundle size by dynamically importing components only when they are needed.
+  <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.
   </x-card>
-  <x-card data-title="Payment Operations" data-icon="lucide:credit-card">
-    Functionality to manage subscriptions, process refunds, view invoices, and handle metered billing.
+  <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>
 </x-cards>
 
 ## How It Works
 
-The library is built around a provider pattern. You wrap your application, or a relevant part of your component tree, with a `PaymentProvider`. This provider handles authentication, API communication, and state management. Components rendered within this provider can then access the payment context to perform actions and display data.
-
-This architecture decouples your UI components from the direct handling of API requests, making your code cleaner and easier to maintain.
+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
+```d2 High-Level Architecture
 direction: down
 
-"Your React Application": {
-  "PaymentProvider": {
-    shape: package
-    "CheckoutForm"
-    "CheckoutDonate"
-    "CustomerInvoiceList"
-  }
+User: {
+  shape: c4-person
 }
 
-"Blocklet Environment": {
-  "Payment Service": {
-    shape: cloud
-  }
-}
+Your-Application: {
+  label: "Your Application"
+  shape: rectangle
 
-"Your React Application.PaymentProvider" -> "Blocklet Environment.Payment Service": "Communicates via API"
-```
+  PaymentProvider: {
+    label: "PaymentProvider"
+    shape: rectangle
 
-Here is a basic example of how to integrate the `CheckoutForm`:
+    Payment-Components: {
+      label: "Payment Components"
+      shape: rectangle
+      grid-columns: 2
 
-```tsx
-import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+      CheckoutForm: { label: "CheckoutForm" }
+      CheckoutTable: { label: "CheckoutTable" }
+      CheckoutDonate: { label: "CheckoutDonate" }
+      CustomerInvoiceList: { label: "CustomerInvoiceList" }
+    }
+  }
+}
 
-// A custom hook from your application that provides the session context.
-// See the PaymentProvider documentation for setup details.
-import { useSessionContext } from './session-context';
+Payment-Kit-Backend: {
+  label: "Payment Kit Backend"
+  shape: cylinder
+}
 
-function App() {
-  const { session, connectApi } = useSessionContext();
+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"
 
-  return (
-    <PaymentProvider session={session} connect={connectApi}>
-      <CheckoutForm 
-        id="plink_xxx" // Payment Link ID
-        mode="inline"  // Embed directly in your UI
-        showCheckoutSummary={true}
-        onChange={(state) => console.log('Checkout State:', state)}
-      />
-    </PaymentProvider>
-  );
-}
 ```
 
-In this example, `useSessionContext` is a custom hook within your application responsible for managing user session state. It should provide the `session` object and the `connect` function required by the `PaymentProvider`. For a detailed guide on setting up this context, please refer to the [PaymentProvider](./providers-payment-provider.md) documentation.
+## 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.
 
 ## Next Steps
 
-To begin integrating payments into your application, proceed to the next section for a step-by-step guide.
+Now that you have an overview of what `@blocklet/payment-react` offers, the best way to learn is by building something.
 
-<x-card data-title="Getting Started" data-href="/getting-started" data-icon="lucide:arrow-right">
-  Install the library and build your first functional payment form.
-</x-card>
+Dive into our [Getting Started](./getting-started.md) guide to install the library and create your first payment form in minutes.