@tuwaio/nova-transactions 0.0.14 → 0.0.16

package/README.md

@@ -4,76 +4,92 @@
 [![License](https://img.shields.io/npm/l/@tuwaio/nova-transactions.svg)](./LICENSE)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/TuwaIO/nova-uikit/release.yml?branch=main)](https://github.com/TuwaIO/nova-uikit/actions)
 
-The official React UI component library for the Pulsar transaction engine. Provides accessible modals, toasts, and history widgets to visualize transaction states.
+The official React UI component library for the Pulsar transaction engine. It provides a suite of pre-built, accessible, and highly customizable modals, toasts, and history widgets to visualize the entire transaction lifecycle.
 
-## Architecture
+---
+
+## 🏛️ Architecture
 
 This package provides the **View Layer** for TUWA's transaction tracking ecosystem. It works by consuming the state from your headless Pulsar store and rendering the appropriate UI.
 
-You must connect your Pulsar store's state and actions to the `<NovaProvider />` component via props.
+You must connect your Pulsar store's state and actions to the `<NovaProvider />` component, which acts as a self-contained UI manager that renders modals and toasts via React Portals.
+
+---
+
+## ✨ Core Features
+
+-   **🧩 Pre-built UI Suite:** A set of accessible components including `TrackingTxModal`, `WalletInfoModal`, and `ToastContainer`, all managed internally by the `NovaProvider`.
+-   **🔌 Plug-and-Play Integration:** Once connected to your Pulsar store, the UI automatically reacts to all transaction state changes.
+-   **🌐 Internationalization (i18n):** Built-in support for multiple languages with easy overrides for all text content via the `labels` prop.
+-   **🎨 Highly Customizable:** Styled with `@tuwaio/nova-core` to be easily themed using CSS variables. Almost every sub-component can be replaced with your own implementation via the `customization` prop.
 
-## Core Features
+---
 
--   **🧩 UI Components:** A suite of pre-built, accessible components including `TransactionModal`, `ToastContainer`, and `WalletInfoModal`, all managed internally.
--   **🔌 Simple Integration:** Once connected to your Pulsar store, the UI automatically reacts to transaction state changes.
--   **🌐 Internationalization (i18n):** Built-in support for multiple languages and easy overrides for all text content.
--   **🎨 Highly Customizable:** Styled with `@tuwaio/nova-core` to be easily themed using Tailwind CSS.
+## 💾 Installation
 
-## Installation
+First, install all required packages for the Pulsar & Nova stack.
 
-1.  Install all the required TUWA packages:
+Next, you need to install a few peer dependencies that `nova-transactions` relies on for UI rendering.
 
-    ```bash
-    pnpm add @tuwaio/nova-transactions @tuwaio/nova-core @tuwaio/pulsar-core @tuwaio/pulsar-evm @tuwaio/pulsar-react
-    ```
+```bash
+# Using pnpm
+pnpm add react-toastify framer-motion @radix-ui/react-dialog @heroicons/react @bgd-labs/react-web3-icons @tuwaio/pulsar-core @tuwaio/nova-core
 
-2.  This package relies on several peer dependencies. Install them if you haven't already:
+# Using npm
+npm install react-toastify framer-motion @radix-ui/react-dialog @heroicons/react @bgd-labs/react-web3-icons @tuwaio/pulsar-core @tuwaio/nova-core
 
-    ```bash
-    pnpm add react react-dom wagmi viem react-toastify framer-motion @radix-ui/react-dialog
-    ```
+# Using yarn
+yarn add react-toastify framer-motion @radix-ui/react-dialog @heroicons/react @bgd-labs/react-web3-icons @tuwaio/pulsar-core @tuwaio/nova-core
+````
 
-## Getting Started
+-----
 
-To use this library, you must render the `<NovaProvider />` component at the top level of your application and pass the state and actions from your Pulsar store to it as props.
+## 🚀 Getting Started
 
-Here is a complete example of a `providers.tsx` file that configures both systems:
+To use this library, you must render the `<NovaProvider />` component at a high level in your application and pass the state and actions from your Pulsar store to it as props.
+
+Here is a complete example of a `Providers.tsx` file that configures the entire system.
 
 ```tsx
-// app/providers.tsx or similar
+// src/providers/index.tsx
 'use client';
 
-import { WagmiProvider, useAccount } from 'wagmi';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { NovaProvider } from '@tuwaio/nova-transactions';
-
-// Import your custom Pulsar hook and the TransactionInitializer component
-import { usePulsarStore } from '../hooks/usePulsarStore';
-import { TransactionInitializer } from '../components/TransactionInitializer';
+import {usePulsar} from '@/store/pulsar';
+import {NovaProvider} from '@tuwaio/nova-transactions';
+import {useAccount} from 'wagmi';
+import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
+import {WagmiProvider} from 'wagmi';
+import {PulsarInitializer} from '@/components/PulsarInitializer';
+import {wagmiConfig, chains, pulsarStore} from '@/configs'; // Your app's configs
+import {TransactionAdapter} from '@tuwaio/pulsar-core';
+import {evmAdapter} from '@tuwaio/pulsar-evm';
 
 // Import required CSS
 import '@tuwaio/nova-core/dist/index.css';
 import '@tuwaio/nova-transactions/dist/index.css';
 import 'react-toastify/dist/ReactToastify.css';
 
-// Your Wagmi Config
-import { wagmiConfig, appChains } from './wagmi';
-
 const queryClient = new QueryClient();
 
-export function Providers({ children }: { children: React.ReactNode }) {
-  // 1. Get state and actions from your Pulsar store hook
-  const { transactionsPool, initialTx, handleTransaction, closeTxTrackedModal } = usePulsarStore();
-  
+export function Providers({children}: { children: React.ReactNode }) {
+  // 1. Get live state and actions from your Pulsar store hook
+  const {
+    transactionsPool,
+    initialTx,
+    handleTransaction,
+    closeTxTrackedModal,
+    actions,
+  } = usePulsar();
+
   // 2. Get live wallet data from wagmi
-  const { address, chain } = useAccount();
+  const {address, chain} = useAccount();
 
   return (
     <WagmiProvider config={wagmiConfig}>
       <QueryClientProvider client={queryClient}>
-        {/* TransactionInitializer handles rehydrating the Pulsar store */}
-        <TransactionInitializer />
-          
+        {/* PulsarInitializer handles rehydrating the store on page load */}
+        <PulsarInitializer/>
+
         {/* Your application's pages */}
         {children}
 
@@ -84,15 +100,14 @@ export function Providers({ children }: { children: React.ReactNode }) {
           initialTx={initialTx}
           handleTransaction={handleTransaction}
           closeTxTrackedModal={closeTxTrackedModal}
-          
-          // Pass live wallet and chain data
-          walletAddress={address}
-          chain={chain}
-          
+          actions={actions}
+
+          // Pass live wallet and adapter data
+          connectedWalletAddress={address}
+          connectedAdapterType={chain?.id ? TransactionAdapter.EVM : undefined} // Example for EVM
+
           // Pass static configuration
-          appChains={appChains}
-          config={wagmiConfig}
-          // actions={...} // Pass retry actions if you have them
+          adapters={[evmAdapter(wagmiConfig, chains)]}
         />
       </QueryClientProvider>
     </WagmiProvider>
@@ -100,57 +115,39 @@ export function Providers({ children }: { children: React.ReactNode }) {
 }
 ```
 
-## Usage Example
-
-Once the `NovaProvider` is set up correctly, you can use your custom `usePulsarStore` hook anywhere to track transactions. The UI components rendered by `NovaProvider` will automatically appear and update.
-
-```tsx
-// components/IncrementButton.tsx
-'use client';
-
-// Import your custom hook, created as shown in the pulsar-react docs
-import { usePulsarStore } from '../hooks/usePulsarStore';
-// ... other imports
-
-export function IncrementButton() {
-  const { handleTransaction } = usePulsarStore();
-
-  const handleIncrement = async () => {
-    // Calling handleTransaction updates the Pulsar store's state.
-    // NovaProvider receives this new state via props and renders the appropriate UI.
-    await handleTransaction({
-      actionFunction: () => { /* ... your contract write call ... */ },
-      params: { /* ... your transaction metadata ... */ }
-    });
-  };
-
-  return <button onClick={handleIncrement}>Increment</button>;
-}
-```
-
-## Internationalization (i18n)
+## Customization
 
-You can easily override the default English text by passing a `labels` prop to the `NovaProvider`. Here is an example with German translations:
+You can easily override the default English text by passing a `labels` prop, or replace entire components using the `customization` prop.
 
 ```tsx
 <NovaProvider
+  // 1. Override text labels
   labels={{
-    transaction: {
-      title: 'Transaktion',
-      pending: 'Ausstehend...',
+    statuses: {
+      pending: 'In Bearbeitung...',
       success: 'Erfolgreich!',
       failed: 'Fehlgeschlagen!',
     },
     // ... other keys
   }}
+
+  // 2. Override a component (e.g., the status badge)
+  customization={{
+    components: {
+      statusBadge: ({ tx }) => <MyCustomBadge status={tx.status} />,
+    }
+  }}
+
   // ... other required props
 />
 ```
 
-## Contributing
+-----
+
+## 🤝 Contributing
 
-Contributions are welcome! Please read our main **[Contribution Guidelines](https://github.com/TuwaIO/workflows/blob/main/CONTRIBUTING.md)**.
+Contributions are welcome\! Please read our main **[Contribution Guidelines](https://github.com/TuwaIO/workflows/blob/main/CONTRIBUTING.md)**.
 
-## License
+## 📄 License
 
-This project is licensed under the **Apache-2.0 License**.
+This project is licensed under the **Apache-2.0 License** - see the [LICENSE](./LICENSE) file for details.