@blocklet/payment-react 1.20.5 → 1.20.6

package/docs/guides-utilities.md

@@ -1,235 +1,197 @@
 # 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.
+The `@blocklet/payment-react` library exports a suite of utility functions and classes designed to simplify common tasks such as making API requests, managing cache, handling dates, formatting prices, and setting up internationalization. These tools are built to work seamlessly with the library's components and providers.
 
 ## 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).
+The library provides a pre-configured Axios instance for making API requests to your payment backend. It automatically handles base URLs and other necessary configurations.
 
-```tsx
+```tsx API Client Usage icon=logos:javascript
 import { api } from '@blocklet/payment-react';
 
 // Basic GET request
-const response = await api.get('/api/payments');
+const getPayments = async () => {
+  const response = await api.get('/api/payments');
+  return response.data;
+};
 
-// POST request with a body
-const data = await api.post('/api/checkout', { amount: 100 });
+// POST request with a payload
+const createCheckout = async (amount) => {
+  const data = await api.post('/api/checkout', { amount });
+  return data;
+};
 
-// Request with query parameters
-const results = await api.get('/api/invoices', {
-  params: { status: 'paid' }
-});
+// GET request with query parameters
+const getPaidInvoices = async () => {
+  const results = await api.get('/api/invoices', { 
+    params: { status: 'paid' } 
+  });
+  return results.data;
+};
 
-// Request with custom configuration
-const config = {
-  headers: { 'Custom-Header': 'value' }
+// PUT request with additional configuration
+const updateSubscription = async (data) => {
+  const config = { 
+    headers: { 'Custom-Header': 'value' }
+  };
+  const response = await api.put('/api/subscription', data, config);
+  return response.data;
 };
-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
+To optimize performance and reduce redundant network requests, you can use the `CachedRequest` class. It provides a simple way to cache data with configurable strategies and time-to-live (TTL).
 
-subgraph "Cache Hit" {
-  direction: down
-  style.stroke: "#4CAF50"
-  return_cached: "Return cached data"
-}
+### Configuration Options
 
-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
-}
+When creating a `CachedRequest` instance, you can provide the following options:
 
-cache_check -> return_cached: Yes
-cache_check -> api_call: No
-```
+| Option | Type | Description | Default |
+| :--- | :--- | :--- | :--- |
+| `strategy` | `'session' \| 'local' \| 'memory'` | The storage mechanism for the cache. | `'session'` |
+| `ttl` | `number` | The cache's time-to-live in milliseconds. A value of `0` means no expiration. | `0` |
 
-### Usage
+### Usage Example
 
-To use it, create an instance of `CachedRequest` with a unique key, a data-fetching function, and optional configuration.
+Here’s how to create and use a cached request to fetch product prices.
 
-```tsx
+```tsx CachedRequest Example icon=logos:javascript
 import { CachedRequest, api } from '@blocklet/payment-react';
 
-// Create a cached request instance
+// 1. Create a cached request instance
 const priceRequest = new CachedRequest(
-  'product-prices',
+  'product-prices', 
   () => api.get('/api/prices'),
   {
-    strategy: 'session',  // 'session' | 'local' | 'memory'
+    strategy: 'session',  // Cache data in sessionStorage
     ttl: 5 * 60 * 1000   // Cache for 5 minutes
   }
 );
 
-// Use the cached request
+// 2. Use the cached request in your component
 async function fetchPrices() {
-  // This will use the cache if available and not expired
+  // This will use the cache if it's available and not expired
   const prices = await priceRequest.fetch();
-
-  // To bypass the cache and force a network request
+  
+  // To bypass the cache and force a fresh data fetch
   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). |
+// 3. Clear the cache when data changes
+async function updatePrices() {
+  await api.post('/api/prices', newPriceData);
+  priceRequest.clearCache(); // Or await priceRequest.fetch(true);
+}
+```
 
-## Date Handling with dayjs
+## Date Handling
 
-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.
+The library re-exports a pre-configured `dayjs` instance with useful plugins like `relativeTime`, `utc`, and `timezone` already included. You can use this for any date and time manipulation needs.
 
-```tsx
+```tsx Date Handling with dayjs icon=logos:javascript
 import { dayjs } from '@blocklet/payment-react';
 
 // Format the current date
-const formattedDate = dayjs().format('YYYY-MM-DD');
+const formattedDate = dayjs().format('YYYY-MM-DD HH:mm');
 
-// Parse a timestamp and get its Unix value
-const timestamp = 1672531200000;
-const dateObject = dayjs(timestamp);
-const unixValue = dateObject.unix();
+// Parse a timestamp
+const dateFromTimestamp = dayjs(1672531200000);
+const unixTimestamp = dateFromTimestamp.unix();
 
-// Display relative time
+// Calculate 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"
+const relativeTime = dayjs().from(fiveMinutesAgo); // "5 minutes ago"
 ```
 
-### 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.
+`@blocklet/payment-react` includes built-in support for i18n. You can create your own translator or merge your translations with the library's defaults.
 
-### `createTranslator`
+### Creating a Translator
 
-You can create your own translator instance with custom language packs.
+Use the `createTranslator` function to set up your own translation instance.
 
-```tsx
+```tsx Custom Translator Setup icon=logos:javascript
 import { createTranslator } from '@blocklet/payment-react';
 
 const myTranslations = {
-  en: {
+  en: { 
     checkout: { title: 'Complete Payment' }
   },
-  zh: {
+  zh: { 
     checkout: { title: '完成支付' }
   }
 };
 
 const translator = createTranslator({ fallbackLocale: 'en' }, myTranslations);
 
-console.log(translator('checkout.title', 'zh')); // Outputs: '完成支付'
+translator('checkout.title', 'zh'); // '完成支付'
 ```
 
 ### Merging with Library Translations
 
-To leverage the built-in translations for payment components, you can merge them with your application's translation files.
+To leverage the library's built-in translations for components while adding your own, you can merge them together.
 
-```tsx
+```tsx Merging Translations icon=logos:javascript
 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
+// Your application's translations
+import en from './locales/en';
+import zh from './locales/zh';
 
 export const translations = merge(
   {
-    zh,
     en,
+    zh,
   },
   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.
+## Formatting Utilities
 
-```tsx
-import { createLazyComponent } from '@blocklet/payment-react';
+Several helper functions are available to format data for display.
 
-const LazyLoadedComponent = createLazyComponent(async () => {
-  // Dynamically import the component and its dependencies
-  const [{ Component }, { useHook }] = await Promise.all([
-    import('./Component'),
-    import('./hooks')
-  ]);
+| Function | Description |
+| :--- | :--- |
+| `formatPrice` | Formats a price object into a human-readable string, considering recurring intervals. |
+| `formatRecurring` | Formats a recurring object into strings like "monthly" or "every 3 months". |
+| `formatBNStr` | Formats a BigNumber string from a base unit into a token value with specified precision. |
+| `formatNumber` | Formats a number or string with thousand separators and precision. |
+| `formatError` | Parses various error formats (GraphQL, Joi, Axios) into a readable string. |
 
-  // Make dependencies available if needed
-  globalThis.__DEPENDENCIES__ = { useHook };
+```tsx Formatting Example icon=logos:javascript
+import { formatNumber, formatRecurring } from '@blocklet/payment-react';
 
-  return Component;
-});
+// Format a number
+const formatted = formatNumber('1234567.89123', 2); // "1,234,567.89"
 
-function App() {
-  return (
-    <div>
-      {/* This component will be loaded on demand */}
-      <LazyLoadedComponent />
-    </div>
-  );
-}
+// Format a recurring interval
+const monthly = formatRecurring({ interval: 'month', interval_count: 1 }); // "per month"
+const quarterly = formatRecurring({ interval: 'month', interval_count: 3 }); // "Quarterly"
 ```
 
----
+## Validation Utilities
+
+The library also includes helpers for form validation.
+
+### `validatePostalCode`
+
+Checks if a given postal code is valid for a specific country.
+
+```tsx Postal Code Validation icon=logos:javascript
+import { validatePostalCode } from '@blocklet/payment-react';
+
+// Returns true
+const isValidUS = validatePostalCode('90210', 'US');
+
+// Returns false
+const isInvalidUS = validatePostalCode('ABC-123', 'US');
 
-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.
+// Returns true for a UK postal code
+const isValidGB = validatePostalCode('SW1A 0AA', 'GB');
+```

package/docs/guides.md

@@ -1,95 +1,18 @@
 # 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.
+Welcome to the guides section. Here, you'll find in-depth articles on advanced topics that go beyond individual component usage. These guides are designed to help you customize the library's appearance and leverage its powerful utility functions to build more sophisticated payment solutions.
 
-These guides are designed for developers looking to move beyond basic integration and fully leverage the capabilities of `@blocklet/payment-react`.
+Explore the guides below to master theming and utilities.
 
-<x-cards>
+<x-cards data-columns="2">
   <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.
+    Learn how to customize the look and feel of payment components to match your application's design system. This guide covers using the built-in theme provider, overriding styles with Material-UI theme options, and applying custom CSS.
   </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.
+    Discover a collection of powerful utility functions for handling API requests, caching data, formatting dates and amounts, and managing internationalization. This guide will help you write cleaner and more efficient code.
   </x-card>
 </x-cards>
 
----
+After exploring these guides, you might be interested in learning about the custom React hooks provided by the library.
 
-## 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.
+➡️ **Next: [Hooks](./hooks.md)**

package/docs/hooks-use-mobile.md

@@ -1,70 +1,84 @@
 # 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.
+The `useMobile` hook is a convenient utility for detecting if the application is being viewed on a mobile-sized device. It helps in creating responsive layouts and components directly within your React logic by leveraging Material-UI's breakpoint system.
 
-This hook simplifies responsive logic by abstracting away the underlying `useTheme` and `useMediaQuery` calls from Material-UI.
+## How It Works
+
+Internally, `useMobile` uses Material-UI's `useTheme` and `useMediaQuery` hooks. It checks the current screen width against the theme's defined breakpoints to determine if the viewport qualifies as "mobile".
 
 ## 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.
+Here's a simple example of how to use the `useMobile` hook to conditionally render content.
 
-```tsx
+```tsx ResponsiveComponent.tsx icon=logos:react
 import { useMobile } from '@blocklet/payment-react';
-import Typography from '@mui/material/Typography';
+import { Typography, Box } from '@mui/material';
 
 function ResponsiveComponent() {
-  const { isMobile } = useMobile();
+  const { isMobile, mobileSize } = useMobile();
 
   return (
-    <Typography variant="h5">
-      {isMobile ? 'This is the mobile view.' : 'This is the desktop view.'}
-    </Typography>
+    <Box p={2}>
+      <Typography variant="h5">
+        Responsive Content
+      </Typography>
+      {
+        isMobile ? (
+          <Typography>
+            This is the mobile view. The screen is {mobileSize} or smaller.
+          </Typography>
+        ) : (
+          <Typography>
+            This is the desktop view. The screen is wider than {mobileSize}.
+          </Typography>
+        )
+      }
+    </Box>
   );
 }
-```
 
-In this example, the component will render different text depending on whether the screen width is below the default 'md' (medium) breakpoint.
+export default ResponsiveComponent;
+```
 
 ## 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 `useMobile` hook accepts an optional parameter to customize the breakpoint.
 
-The hook returns an object with two properties:
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `mobilePoint` | `'md' \| 'sm' \| 'lg' \| 'xl' \| 'xs'` | The breakpoint to consider as the mobile threshold. The `isMobile` flag will be true if the screen width is at or below this point. Defaults to `'md'`. |
 
-| 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). |
+### Customizing the Breakpoint
 
-## Example with Custom Breakpoint
+You can easily change the breakpoint by passing a different value.
 
-You can specify a different breakpoint if your application's design requires a different threshold for mobile view.
-
-```tsx
+```tsx CustomBreakpoint.tsx icon=logos:react
 import { useMobile } from '@blocklet/payment-react';
-import Box from '@mui/material/Box';
+import { Typography } from '@mui/material';
 
 function CustomBreakpointComponent() {
-  // Consider 'sm' and below as mobile
-  const { isMobile, mobileSize } = useMobile('sm');
+  // Consider 'sm' (small) screens and below as mobile
+  const { isMobile } = useMobile('sm');
 
   return (
-    <Box sx={{ p: 2, border: '1px solid grey' }}>
-      <p>The mobile breakpoint is set to {mobileSize}.</p>
+    <div>
       {isMobile ? (
-        <p>This layout is optimized for smaller screens.</p>
+        <Typography>Display for small screens</Typography>
       ) : (
-        <p>This layout is for tablets and desktops.</p>
+        <Typography>Display for medium and larger screens</Typography>
       )}
-    </Box>
+    </div>
   );
 }
+
+export default CustomBreakpointComponent;
 ```
 
-This component adjusts its responsive behavior based on the 'sm' (small) breakpoint, providing more granular control over your UI.
+## Return Value
+
+The hook returns an object with the following properties:
+
+| Key | Type | Description |
+| :--- | :--- | :--- |
+| `isMobile` | `boolean` | `true` if the current viewport width is less than or equal to the specified `mobilePoint` breakpoint, otherwise `false`. |
+| `mobileSize` | `string` | A string representing the pixel width of the `mobilePoint` breakpoint (e.g., `"900px"`). |