droplinked-web3-ui 0.0.10 → 0.0.12

package/README.md

@@ -1,75 +1,512 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## React Compiler
-
-The React Compiler is enabled on this template. See [this documentation](https://react.dev/learn/react-compiler) for more information.
-
-Note: This will impact Vite dev & build performances.
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
-
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+# 💎 droplinked-web3-ui
+
+A React library for Web3 payments and NFT claims on the Droplinked platform.
+
+![Version](https://img.shields.io/npm/v/droplinked-web3-ui)
+![License](https://img.shields.io/npm/l/droplinked-web3-ui)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install droplinked-web3-ui
+```
+
+---
+
+## 🚀 Main Dependencies
+
+This project uses the following dependencies:
+
+| Package | Version | Description |
+|---------|---------|-------------|
+| 🌐 `droplinked-web3-kit` | ^1.0.7 | Core Web3 library for blockchain interaction |
+| 🎨 `droplinked-ui-kit` | ^0.0.38 | Shared UI components |
+| ⚡ `@chakra-ui/react` | ^3.32.0 | UI framework |
+| 🏪 `zustand` | ^5.0.11 | State management |
+| 🔄 `react-query` | ^3.39.3 | API request management |
+| 📡 `axios` | ^1.13.5 | HTTP client |
+
+---
+
+## 💳 Component Usage
+
+### DroplinkedWeb3Ui - Unified Web3 Component 🚀
+
+Main component for all Web3 operations. Use the `action` prop to specify the operation type:
+
+```tsx
+import { DroplinkedWeb3Ui, Actions } from 'droplinked-web3-ui';
+```
+
+#### Available Actions
+
+```typescript
+enum Actions {
+  Payment = 'payment',      // 💳 Cryptocurrency payments
+  ClaimNFT = 'claimNFT',    // 🎨 NFT claims
+}
+```
+
+---
+
+### 1️⃣ Payment Action 💰
+
+Process cryptocurrency payments:
+
+```tsx
+import { DroplinkedWeb3Ui, Actions } from 'droplinked-web3-ui';
+
+function PaymentPage() {
+  return (
+    <DroplinkedWeb3Ui
+      action={Actions.Payment}
+      inputs={{
+        cartId: "cart-id-here",
+        shopId: "shop-id-here",
+        price: 100,
+        priceInShopCurrency: 100,
+        abbreviation: "USD",
+        symbol: "$",
+        onError: (error) => console.error(error),
+        onSuccess: (orderId) => console.log('Success:', orderId),
+      }}
+    />
+  );
+}
+```
+
+#### 📝 Payment Inputs
+
+| Prop | Type | Description |
+|------|------|-------------|
+| 🛒 `cartId` | `string` | Shopping cart ID |
+| 🏪 `shopId` | `string` | Shop ID |
+| 💵 `price` | `number` | Payment amount |
+| 💱 `priceInShopCurrency` | `number` | Amount in shop currency |
+| 🏷️ `abbreviation` | `string` | Currency symbol (e.g., USD) |
+| 💲 `symbol` | `string` | Display symbol (e.g., $) |
+| ❌ `onError` | `(error: string) => void` | Error callback |
+| ✅ `onSuccess` | `(orderId?: string) => void` | Success callback |
+
+---
+
+### 2️⃣ ClaimNFT Action 🎨
+
+Claim NFTs after payment:
+
+```tsx
+import { DroplinkedWeb3Ui, Actions } from 'droplinked-web3-ui';
+
+function ClaimPage() {
+  return (
+    <DroplinkedWeb3Ui
+      action={Actions.ClaimNFT}
+      inputs={{
+        orderId: "order-id-here",
+        skuId: "sku-id-here",
+        buttonText: "Claim NFT",
+        isButtonDisabled: false,
+        onError: (message) => console.error(message),
+        onSuccess: (txHash) => console.log('Claimed:', txHash),
+      }}
+    />
+  );
+}
 ```
+
+#### 📝 ClaimNFT Inputs
+
+| Prop | Type | Description |
+|------|------|-------------|
+| 📋 `orderId` | `string` | Order ID |
+| 🏷️ `skuId` | `string` | SKU ID |
+| 🔘 `buttonText` | `string` | Button text |
+| 🚫 `isButtonDisabled` | `boolean` | Button disabled state |
+| ❌ `onError` | `(message: string) => void` | Error callback |
+| ✅ `onSuccess` | `(txHash: string) => void` | Success callback |
+
+---
+
+### Type Safety ✨
+
+The component uses TypeScript generics to provide type-safe inputs based on the action:
+
+```tsx
+// ✅ TypeScript knows inputs should be PaymentInputs
+<DroplinkedWeb3Ui
+  action={Actions.Payment}
+  inputs={{
+    cartId: "...",      // Autocomplete works!
+    // skuId is NOT suggested here ❌
+  }}
+/>
+
+// ✅ TypeScript knows inputs should be ClaimNFTInputs
+<DroplinkedWeb3Ui
+  action={Actions.ClaimNFT}
+  inputs={{
+    orderId: "...",     // Autocomplete works!
+    // cartId is NOT suggested here ❌
+  }}
+/>
+```
+
+---
+
+## 🛠️ Development
+
+### 📁 Project Structure
+
+```
+📦 src/
+├── 📂 components/
+│   ├── 📂 modals/                    # 🪟 Modals
+│   │   └── 📂 wallet-connection/     # 🔗 Wallet connection modal
+│   ├── 📂 pay-with-crypto-element/   # 💸 Crypto payment element
+│   ├── 📂 claim-nft-element/         # 🎨 NFT claim element
+│   └── 📂 common/                    # 🔧 Shared components
+├── 📂 context/
+│   └── 📂 dropWeb3Context/           # 🌐 Web3 context
+├── 📂 hooks/                         # ⚓ Custom hooks
+├── 📂 stores/                        # 🏪 Zustand stores
+├── 📂 apis/                          # 🔌 API services
+└── 📂 utils/                         # 🛠️ Utilities
+```
+
+---
+
+### 🪟 Modals
+
+Modals are located in `src/components/modals/` and managed using the `useModals` hook:
+
+```tsx
+const {
+  activeModal,
+  openConnectModal,          // 🔗 Open wallet connection modal
+  openBrowseWallets,         # 📱 Open wallet list modal
+  openSelectNetworkModal,    # 🌐 Open network selection modal
+  openWalletConnectionModal, # 🔌 Open wallet connection modal
+  openManageWalletsModal,    # 🎛️ Open wallet management modal
+  openSelectTokenModal,      # 🪙 Open token selection modal
+  openPaymentProcessModal,   # 💳 Open payment process modal
+  openClaimProcessModal,     # 🎁 Open claim process modal
+  closeModal,                # ❌ Close active modal
+} = useModals();
+```
+
+---
+
+## 🪝 Hooks
+
+### 🎯 useDropWeb3
+
+Main hook to access the `droplinked-web3-kit` library instance:
+
+```tsx
+import { useDropWeb3 } from '@/context/dropWeb3Context/useDropWeb3';
+
+function MyComponent() {
+  const { web3, provider } = useDropWeb3();
+  
+  // web3: instance of DropWeb3 class 🚀
+  // provider: provider for wallet connections 🔗
+}
+```
+
+> ⚠️ **Note:** This hook must be used inside `DropWeb3Provider`.
+
+---
+
+### 💳 usePayWithCrypto
+
+Hook for managing crypto payments:
+
+```tsx
+import { usePayWithCrypto } from '@/hooks/usePayWithCrypto';
+
+function MyComponent() {
+  const { 
+    hasConnectedWallets,  # ✅ boolean - Whether connected wallets exist
+    connectedWallets,     # 👛 IWallet[] - List of connected wallets
+    isLoading,           # ⏳ boolean - Loading state
+    loadWallets,         # 🔄 () => Promise<void> - Load wallets
+  } = usePayWithCrypto();
+}
+```
+
+---
+
+### 🪙 useTokenBalances
+
+Hook for fetching token balances:
+
+```tsx
+import { useTokenBalances } from '@/hooks/useTokenBalances';
+
+function MyComponent() {
+  useTokenBalances(hasConnectedWallets);  # 🔄 Updates token balances
+}
+```
+
+---
+
+### 🪟 useModals
+
+Hook for managing modals (explained above).
+
+---
+
+### 👛 useWallets
+
+Hook for managing wallets.
+
+---
+
+### 💰 useFormattedAmount
+
+Hook for formatting financial amounts.
+
+---
+
+## 🏪 Zustand Stores
+
+### 💳 paymentUiStore
+
+Manages payment state:
+
+```tsx
+import { usePaymentUiStore } from '@/stores/paymentUiStore';
+
+const {
+  cartId,                     # 🛒
+  price,                      # 💵
+  abbreviation,               # 🏷️
+  symbol,                     # 💲
+  onError,                    # ❌
+  onMainProcessSuccess,       # ✅
+  setPaymentUiData,           # 📝 (props) => set state
+  currentDescription,         # 📄 Current process description
+  currentError,               # ⚠️ Current error
+  currentErrorDescription,    # 📋 Error description
+} = usePaymentUiStore();
+```
+
+---
+
+### 🎨 claimNftStore
+
+Manages NFT claim state:
+
+```tsx
+import { useClaimNftStore } from '@/stores/claimNftStore';
+
+const {
+  orderId,                    # 📋
+  skuId,                      # 🏷️
+  onError,                    # ❌
+  onMainProcessSuccess,       # ✅
+  buttonText,                 # 🔘
+  isButtonDisabled,           # 🚫
+  setClaimNftData,            # 📝 (data) => set state
+  currentDescription,         # 📄
+  currentError,               # ⚠️
+  currentErrorDescription,    # 📋
+} = useClaimNftStore();
+```
+
+---
+
+### 🪟 modalStore
+
+Manages modal state:
+
+```tsx
+import { useModalStore } from '@/stores/modalStore';
+
+const {
+  activeModal,          # 🪟 ModalType - Active modal
+  openModal,            # 📂 (modal) => Open modal
+  closeModal,           # ❌ () => Close modal
+  closeAndOpen,         # 🔄 (current, next, data?) => Close and open
+} = useModalStore();
+```
+
+#### 📋 ModalType Values
+
+| Modal | Description |
+|-------|-------------|
+| 🔗 `'connectWallet'` | Connect wallet modal |
+| 📱 `'browseWallets'` | Browse wallets modal |
+| 📥 `'getWallet'` | Get wallet modal |
+| 🌐 `'selectNetwork'` | Select network modal |
+| 🔌 `'walletConnection'` | Wallet connection modal |
+| 🎛️ `'manageWallets'` | Manage wallets modal |
+| 🪙 `'selectToken'` | Select token modal |
+| 💳 `'paymentProcess'` | Payment process modal |
+| 🎁 `'claimProcess'` | Claim process modal |
+
+---
+
+### 👛 walletStore
+
+Manages wallet state:
+
+```tsx
+import { useWalletStore } from '@/stores/walletStore';
+
+const {
+  allWallets,               # 📱 IWallet[] - All wallets
+  selectedWallet,           # 👆 IWallet \| null - Selected wallet
+  selectedConnectedWallet,  # 🔗 IWallet \| null - Selected connected wallet
+  setAllWallets,            # 📝 (wallets) => set wallets
+  setSelectedWallet,        # 📝 (wallet) => set selected
+  setSelectedConnectedWallet, # 📝
+} = useWalletStore();
+```
+
+---
+
+### 🪙 tokenStore
+
+Manages token state:
+
+```tsx
+import { useTokenStore } from '@/stores/tokenStore';
+
+const {
+  selectedToken,     # 🪙 Selected token
+  setSelectedToken,  # 📝 (token) => set token
+} = useTokenStore();
+```
+
+---
+
+### 📋 orderStore
+
+Manages order state.
+
+---
+
+## 🧩 Main Components
+
+### 🌐 DropWeb3Provider
+
+Main provider for Web3 access:
+
+```tsx
+import { DropWeb3Provider } from '@/context/dropWeb3Context/DropWeb3Context';
+
+<DropWeb3Provider>
+  <YourComponents />
+</DropWeb3Provider>
+```
+
+> 💡 This provider is automatically included in `DroplinkedWeb3Ui`.
+
+---
+
+### 💸 PayWithCrypto
+
+Internal payment UI component used by `DroplinkedWeb3Ui` when `action={Actions.Payment}`. Includes:
+- 👛 Display of connected wallets
+- 🪙 Token selection
+- 💳 Payment process
+
+---
+
+### 🎨 ClaimNftUi
+
+Internal NFT claim UI component used by `DroplinkedWeb3Ui` when `action={Actions.ClaimNFT}`.
+
+---
+
+## 🔌 API Services
+
+Services are located in `src/apis/`:
+
+| Service | Path | Description |
+|---------|------|-------------|
+| 💳 Payment | `payment/services.ts` | Payment services |
+| 📋 Orders | `orders/services.ts` | Order services |
+| 🌐 Web3 | `web3/services.ts` | Web3 services |
+
+---
+
+## 🚀 Publishing
+
+To publish a new version:
+
+### 1️⃣ Update the version
+
+```bash
+npm version patch  # 🔧 For small changes
+npm version minor  # ✨ For new features
+npm version major  # ⚠️ For breaking changes
+```
+
+### 2️⃣ Commit and push
+
+```bash
+git add .
+git commit -m "chore: bump version to x.x.x"
+git push origin main
+```
+
+### 3️⃣ Automatic publish ✨
+
+When pushing to the `main` branch, GitHub Actions will automatically:
+1. 🔨 Build the project
+2. 🔄 Compare the version with npm
+3. 🚀 Publish to npm if the version is new
+
+> ⚠️ **Important notes:**
+> - Only changes to `package.json` or workflow trigger the publish
+> - For manual publish, use `workflow_dispatch` in GitHub Actions
+> - Make sure `NPM_TOKEN` is set in repository secrets 🔐
+
+---
+
+## 🔧 Environment Variables
+
+This project uses the following variables (in `.env`):
+
+```env
+# 🧪 Development
+VITE_BASE_API_URL_DEV=https://apiv3dev.droplinked.com
+
+# 🚀 Production
+VITE_BASE_API_URL_MAIN=https://apiv3.droplinked.com
+```
+
+---
+
+## 💻 Development Notes
+
+### 🎯 Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | 🚀 Start development server |
+| `npm run build` | 🔨 Build for production |
+| `npm run lint` | 🔍 Run linter |
+| `npm run preview` | 👁️ Preview production build |
+
+### 🐛 Debug Mode
+
+In `src/utils/variables.ts`, set `appDevelopment` to `true` to display logs 📝
+
+---
+
+## 📄 License
+
+MIT © Droplinked
+
+---
+
+<div align="center">
+
+Made with ❤️ by the Droplinked Team
+
+</div>