💎 droplinked-web3-ui

A React library for Web3 payments and NFT claims on the Droplinked platform.

📦 Installation

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:

import { DroplinkedWeb3Ui, Actions } from 'droplinked-web3-ui';

Available Actions

enum Actions {
  Payment = 'payment',      // 💳 Cryptocurrency payments
  ClaimNFT = 'claimNFT',    // 🎨 NFT claims
}

1️⃣ Payment Action 💰

Process cryptocurrency payments. The component automatically fetches cart and shop data from the API:

import { DroplinkedWeb3Ui, Actions } from 'droplinked-web3-ui';

function PaymentPage() {
  return (
    <DroplinkedWeb3Ui
      action={Actions.Payment}
      inputs={{
        cartId: "cart-id-here",
        shopId: "shop-id-here",
        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 | | ❌ onError | (error: string) => void | Error callback | | ✅ onSuccess | (orderId?: string) => void | Success callback |

💡 Note: The component automatically fetches cart data (price, items) and shop data (currency, symbol) from the API using the provided cartId and shopId.

2️⃣ ClaimNFT Action 🎨

Claim NFTs after payment:

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:

// ✅ 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
│   ├── paymentUiStore.ts             # 💳 Payment UI state
│   ├── cartStore/                    # 🛒 Cart data
│   ├── shopStore/                    # 🏪 Shop data
│   ├── claimNftStore.ts              # 🎨 NFT claim state
│   ├── modalStore.ts                 # 🪟 Modal state
│   ├── walletStore.ts                # 👛 Wallet state
│   ├── tokenStore.ts                 # 🪙 Token state
│   └── orderStore.ts                 # 📋 Order state
├── 📂 apis/                          # 🔌 API services
└── 📂 utils/                         # 🛠️ Utilities

🪟 Modals

Modals are located in src/components/modals/ and managed using the useModals hook:

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:

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:

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:

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 UI state:

import { usePaymentUiStore } from '@/stores/paymentUiStore';

const {
  cartId,                     # 🛒
  shopId,                     # 🏪
  onError,                    # ❌
  onMainProcessSuccess,       # ✅
  setPaymentUiData,           # 📝 (props) => set state
  currentDescription,         # 📄 Current process description
  currentError,               # ⚠️ Current error
  currentErrorDescription,    # 📋 Error description
} = usePaymentUiStore();

💡 Cart price and shop currency are stored in cartStore and shopStore respectively.

🎨 claimNftStore

Manages NFT claim state:

import { useClaimNftStore } from '@/stores/claimNftStore';

const {
  orderId,                    # 📋
  skuId,                      # 🏷️
  onError,                    # ❌
  onMainProcessSuccess,       # ✅
  buttonText,                 # 🔘
  isButtonDisabled,           # 🚫
  setClaimNftData,            # 📝 (data) => set state
  currentDescription,         # 📄
  currentError,               # ⚠️
  currentErrorDescription,    # 📋
} = useClaimNftStore();

🪟 modalStore

Manages modal state:

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:

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:

import { useTokenStore } from '@/stores/tokenStore';

const {
  selectedToken,     # 🪙 Selected token
  setSelectedToken,  # 📝 (token) => set token
} = useTokenStore();

📋 orderStore

Manages order state.

🛒 cartStore

Manages cart data fetched from API:

import { useCartStore } from '@/stores/cartStore';

const {
  cart,           # 🛒 ICart - Cart data
  updateCart,     # 📝 (cart) => Update cart
  resetCart,      # 🔄 () => Reset cart
} = useCartStore();

🏪 shopStore

Manages shop data fetched from API:

import { useShopStore } from '@/stores/shopStore';

const {
  shop,           # 🏪 IShop - Shop data
  updateShop,     # 📝 (shop) => Update shop
} = useShopStore();

🧩 Main Components

🌐 DropWeb3Provider

Main provider for Web3 access:

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 | | 🛒 Cart | cart/services.ts | Cart data fetching | | 🏪 Shop | shop/services.ts | Shop data fetching |

🚀 Publishing

To publish a new version:

1️⃣ Update the version

npm version patch  # 🔧 For small changes
npm version minor  # ✨ For new features
npm version major  # ⚠️ For breaking changes

2️⃣ Commit and push

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):

# 🧪 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

Made with ❤️ by the Droplinked Team