@jerydam/lumina-sdk 0.1.0

package/app/docs/sdk/transaction-confirm/page.tsx

@@ -0,0 +1,331 @@
+'use client'
+
+import { Breadcrumb } from '@/components/docs/breadcrumb'
+import { TableOfContents } from '@/components/docs/table-of-contents'
+import { CodeBlock } from '@/components/docs/code-block'
+import { Callout } from '@/components/docs/callout'
+
+export default function TransactionConfirmPage() {
+  const headings = [
+    { id: 'overview', level: 2, text: 'Overview' },
+    { id: 'props', level: 2, text: 'Props & Configuration' },
+    { id: 'callbacks', level: 2, text: 'Callbacks' },
+    { id: 'transaction-flow', level: 2, text: 'Transaction Flow' },
+    { id: 'examples', level: 2, text: 'Examples' },
+    { id: 'error-handling', level: 2, text: 'Error Handling' },
+  ]
+
+  return (
+    <div className="flex gap-8 max-w-7xl mx-auto px-4 py-8">
+      <main className="flex-1 min-w-0">
+        <Breadcrumb 
+          items={[
+            { label: 'Docs', href: '/docs' },
+            { label: 'SDK', href: '/docs/sdk/lumina-provider' },
+            { label: 'TransactionConfirm' },
+          ]}
+        />
+
+        <div className="mt-8 prose prose-invert max-w-none">
+          <h1>TransactionConfirm Component</h1>
+          
+          <p className="text-lg text-foreground/80">
+            A secure transaction confirmation component that handles user review and approval of blockchain transactions before execution.
+          </p>
+
+          <h2 id="overview">Overview</h2>
+          <p>
+            The <code>TransactionConfirm</code> component provides a modal interface for users to review transaction details before confirmation. It handles gas estimates, fee calculations, and secure confirmation workflows.
+          </p>
+
+          <CodeBlock
+            code={`import { TransactionConfirm } from '@lumina/react'
+
+export default function MyComponent() {
+  return (
+    <TransactionConfirm
+      transactionId="txn_123abc"
+      amount="1.5"
+      recipient="0x742d35Cc6634C0532925a3b844Bc9e7595f42e0d"
+      onConfirm={() => console.log('Confirmed')}
+      onCancel={() => console.log('Cancelled')}
+    />
+  )
+}`}
+            language="typescript"
+            title="Basic Usage"
+          />
+
+          <h2 id="props">Props & Configuration</h2>
+
+          <h3>Required Props</h3>
+          <CodeBlock
+            code={`interface TransactionConfirmProps {
+  // Transaction identifier
+  transactionId: string
+  
+  // Amount to send (in token units)
+  amount: string
+  
+  // Recipient wallet address
+  recipient: string
+  
+  // Token symbol (e.g., 'ETH', 'USDC')
+  tokenSymbol?: string
+  
+  // Transaction type
+  type?: 'send' | 'swap' | 'stake' | 'contract'
+}`}
+            language="typescript"
+            title="Required Props"
+          />
+
+          <h3>Optional Props</h3>
+          <CodeBlock
+            code={`interface TransactionConfirmProps {
+  // Gas settings
+  gasLimit?: string
+  gasPrice?: string
+  maxFeePerGas?: string
+  maxPriorityFeePerGas?: string
+  
+  // Network
+  chainId?: number
+  networkName?: string
+  
+  // Display options
+  showGasDetails?: boolean
+  showEstimatedTime?: boolean
+  theme?: 'light' | 'dark'
+  
+  // Validation
+  maxSlippage?: number
+  skipValidation?: boolean
+  
+  // Metadata
+  metadata?: Record<string, any>
+}`}
+            language="typescript"
+            title="Optional Props"
+          />
+
+          <h2 id="callbacks">Callbacks</h2>
+
+          <CodeBlock
+            code={`interface TransactionConfirmProps {
+  // Called when user confirms transaction
+  onConfirm: (confirmationData: {
+    transactionId: string
+    hash: string
+    signature: string
+    timestamp: number
+  }) => void | Promise<void>
+  
+  // Called when user cancels
+  onCancel: () => void
+  
+  // Called on error
+  onError?: (error: {
+    code: string
+    message: string
+  }) => void
+  
+  // Called when transaction completes
+  onComplete?: (receipt: {
+    hash: string
+    blockNumber: number
+    gasUsed: string
+    status: 'success' | 'failed'
+  }) => void
+}`}
+            language="typescript"
+            title="Callback Functions"
+          />
+
+          <h2 id="transaction-flow">Transaction Flow</h2>
+
+          <p>
+            The TransactionConfirm component follows a specific flow:
+          </p>
+
+          <CodeBlock
+            code={`1. User initiates transaction
+   ↓
+2. TransactionConfirm modal opens
+   ↓
+3. Display transaction details:
+   - From/To addresses
+   - Amount and token
+   - Network info
+   - Gas fees
+   - Estimated time
+   ↓
+4. User reviews and clicks "Confirm"
+   ↓
+5. Component signs transaction
+   ↓
+6. onConfirm callback invoked
+   ↓
+7. Transaction submitted to network
+   ↓
+8. onComplete callback invoked`}
+            language="text"
+            title="Transaction Lifecycle"
+          />
+
+          <h2 id="examples">Examples</h2>
+
+          <h3>Basic ETH Transfer</h3>
+          <CodeBlock
+            code={`'use client'
+
+import { useState } from 'react'
+import { TransactionConfirm } from '@lumina/react'
+
+export default function TransferETH() {
+  const [txId, setTxId] = useState(null)
+  const [status, setStatus] = useState('idle')
+
+  const handleConfirm = async (confirmationData) => {
+    setStatus('confirming')
+    try {
+      const response = await fetch('/api/confirm-transaction', {
+        method: 'POST',
+        body: JSON.stringify(confirmationData),
+      })
+      setStatus('success')
+    } catch (error) {
+      setStatus('error')
+    }
+  }
+
+  return (
+    <TransactionConfirm
+      transactionId={txId}
+      amount="2.5"
+      recipient="0x742d35Cc6634C0532925a3b844Bc9e7595f42e0d"
+      tokenSymbol="ETH"
+      chainId={1}
+      onConfirm={handleConfirm}
+      onCancel={() => setTxId(null)}
+    />
+  )
+}`}
+            language="typescript"
+            title="ETH Transfer Example"
+          />
+
+          <h3>Token Swap with Gas Details</h3>
+          <CodeBlock
+            code={`<TransactionConfirm
+  transactionId="txn_swap_123"
+  amount="100"
+  recipient="0x1111111254fb6c44bac0bed2854e76f90643097d"
+  tokenSymbol="USDC"
+  type="swap"
+  chainId={1}
+  showGasDetails={true}
+  showEstimatedTime={true}
+  maxSlippage={0.5}
+  onConfirm={async (data) => {
+    console.log('Swap confirmed:', data)
+    const tx = await submitSwap(data)
+    console.log('Swap hash:', tx.hash)
+  }}
+  onError={(error) => {
+    console.error('Swap error:', error.message)
+  }}
+  onComplete={(receipt) => {
+    console.log('Swap complete:', receipt.status)
+  }}
+/>`}
+            language="typescript"
+            title="Swap with Gas Details"
+          />
+
+          <h3>Staking with Contract Interaction</h3>
+          <CodeBlock
+            code={`<TransactionConfirm
+  transactionId="txn_stake_456"
+  amount="10"
+  recipient="0x1234567890123456789012345678901234567890"
+  type="contract"
+  chainId={1}
+  metadata={{
+    contractMethod: 'stake',
+    stakingPeriod: '30days',
+    expectedYield: '12.5%',
+  }}
+  onConfirm={async (confirmationData) => {
+    // Handle stake confirmation
+    const stakeTx = await stakeTokens(confirmationData)
+    console.log('Staking initiated:', stakeTx.hash)
+  }}
+/>`}
+            language="typescript"
+            title="Contract Interaction"
+          />
+
+          <h2 id="error-handling">Error Handling</h2>
+
+          <p>
+            Handle various error scenarios:
+          </p>
+
+          <CodeBlock
+            code={`<TransactionConfirm
+  transactionId={txId}
+  amount="1.0"
+  recipient={recipientAddress}
+  onConfirm={handleConfirm}
+  onError={(error) => {
+    switch (error.code) {
+      case 'INSUFFICIENT_BALANCE':
+        console.error('User has insufficient balance')
+        break
+      case 'INVALID_RECIPIENT':
+        console.error('Invalid recipient address')
+        break
+      case 'GAS_ESTIMATION_FAILED':
+        console.error('Failed to estimate gas')
+        break
+      case 'SIGNATURE_REJECTED':
+        console.error('User rejected signature request')
+        break
+      case 'NETWORK_ERROR':
+        console.error('Network connectivity issue')
+        break
+      default:
+        console.error('Unknown error:', error.message)
+    }
+  }}
+/>`}
+            language="typescript"
+            title="Error Handling"
+          />
+
+          <Callout type="info">
+            TransactionConfirm automatically handles gas estimation and fee calculation for the selected network.
+          </Callout>
+
+          <Callout type="warning">
+            Always wait for the onConfirm callback before submitting the transaction. Never bypass the confirmation step.
+          </Callout>
+        </div>
+
+        <div className="flex justify-between mt-12 pt-8 border-t border-white/10">
+          <a href="/docs/sdk/wallet-display" className="text-emerald-400 hover:text-emerald-300">
+            ← Wallet Display
+          </a>
+          <a href="/docs/api/overview" className="text-emerald-400 hover:text-emerald-300">
+            API Overview →
+          </a>
+        </div>
+      </main>
+
+      <aside className="hidden lg:block w-64 flex-shrink-0">
+        <TableOfContents headings={headings} />
+      </aside>
+    </div>
+  )
+}

package/app/docs/sdk/wallet-display/page.tsx

@@ -0,0 +1,224 @@
+import { Breadcrumb } from '@/components/docs/breadcrumb'
+import { CodeBlock } from '@/components/docs/code-block'
+import { Callout } from '@/components/docs/callout'
+
+export const metadata = {
+  title: 'WalletDisplay - SDK Reference',
+  description: 'Show wallet details and enable send/receive with WalletDisplay.',
+}
+
+export default function WalletDisplayPage() {
+  return (
+    <>
+      <Breadcrumb />
+
+      <div className="space-y-8">
+        <div className="space-y-4">
+          <h1 className="text-4xl font-bold text-white">WalletDisplay</h1>
+          <p className="text-lg text-foreground/80">
+            Display wallet information including balance, address, and allow users to send or receive funds. Includes copy-to-clipboard and address explorer links.
+          </p>
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Basic Usage</h2>
+          <CodeBlock
+            code={`'use client'
+
+import { WalletDisplay } from '@lumina/sdk'
+
+export default function WalletPage() {
+  return (
+    <WalletDisplay
+      address="0x742d35Cc6634C0532925a3b844Bc1e8181f42f9f"
+      balance="5.234"
+      network="ethereum"
+    />
+  )
+}`}
+            language="tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Props</h2>
+          <div className="space-y-4">
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">address</p>
+              <p className="text-sm text-foreground/80 mb-2">
+                <span className="text-red-400">Required</span> • <span className="text-blue-400">string</span>
+              </p>
+              <p className="text-sm text-foreground/80">
+                The wallet address to display. Should be a valid Ethereum address.
+              </p>
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">balance</p>
+              <p className="text-sm text-foreground/80 mb-2">
+                <span className="text-red-400">Required</span> • <span className="text-blue-400">string | number</span>
+              </p>
+              <p className="text-sm text-foreground/80">
+                The account balance in native currency (ETH, MATIC, etc).
+              </p>
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">network</p>
+              <p className="text-sm text-foreground/80 mb-2">
+                <span className="text-red-400">Required</span> • <span className="text-blue-400">'ethereum' | 'polygon' | 'arbitrum' | 'optimism'</span>
+              </p>
+              <p className="text-sm text-foreground/80">
+                The blockchain network. Used for explorer links and asset prices.
+              </p>
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">onSend</p>
+              <p className="text-sm text-foreground/80 mb-2">
+                <span className="text-green-400">Optional</span> • <span className="text-blue-400">() =&gt; void</span>
+              </p>
+              <p className="text-sm text-foreground/80">
+                Callback when the "Send" button is clicked.
+              </p>
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">onReceive</p>
+              <p className="text-sm text-foreground/80 mb-2">
+                <span className="text-green-400">Optional</span> • <span className="text-blue-400">() =&gt; void</span>
+              </p>
+              <p className="text-sm text-foreground/80">
+                Callback when the "Receive" button is clicked.
+              </p>
+            </div>
+
+            <div className="p-4 rounded-lg bg-white/5 border border-white/10">
+              <p className="font-semibold text-emerald-400 mb-2">showTokens</p>
+              <p className="text-sm text-foreground/80 mb-2">
+                <span className="text-green-400">Optional</span> • <span className="text-blue-400">boolean</span>
+              </p>
+              <p className="text-sm text-foreground/80">
+                Show list of ERC-20 tokens. Defaults to true.
+              </p>
+            </div>
+          </div>
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">With Callbacks</h2>
+          <CodeBlock
+            code={`<WalletDisplay
+  address="0x742d35Cc6634C0532925a3b844Bc1e8181f42f9f"
+  balance="5.234"
+  network="ethereum"
+  showTokens={true}
+  onSend={() => {
+    console.log('Send button clicked')
+    // Open send modal or navigate
+  }}
+  onReceive={() => {
+    console.log('Receive button clicked')
+    // Show QR code or copy address
+  }}
+/>`}
+            language="tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Full Example with Sending</h2>
+          <CodeBlock
+            code={`'use client'
+
+import { useState } from 'react'
+import { WalletDisplay, TransactionConfirm } from '@lumina/sdk'
+
+export default function WalletPage() {
+  const [showSendModal, setShowSendModal] = useState(false)
+  const [recipient, setRecipient] = useState('')
+
+  return (
+    <div className="p-8 space-y-6">
+      <WalletDisplay
+        address="0x742d35Cc6634C0532925a3b844Bc1e8181f42f9f"
+        balance="5.234"
+        network="ethereum"
+        onSend={() => setShowSendModal(true)}
+      />
+
+      {showSendModal && (
+        <div className="fixed inset-0 bg-black/50 flex items-center justify-center">
+          <div className="bg-card p-6 rounded-lg max-w-md">
+            <h2 className="text-xl font-bold mb-4">Send ETH</h2>
+            <input
+              type="text"
+              placeholder="Recipient address"
+              value={recipient}
+              onChange={(e) => setRecipient(e.target.value)}
+              className="w-full px-4 py-2 rounded-lg bg-white/10 border border-white/20 mb-4"
+            />
+            <button
+              onClick={() => setShowSendModal(false)}
+              className="w-full px-4 py-2 bg-emerald-600 rounded-lg hover:bg-emerald-700"
+            >
+              Proceed
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}`}
+            language="tsx"
+          />
+        </div>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Supported Networks</h2>
+          <div className="grid grid-cols-2 gap-4">
+            {[
+              { name: 'Ethereum', id: 'ethereum' },
+              { name: 'Polygon', id: 'polygon' },
+              { name: 'Arbitrum', id: 'arbitrum' },
+              { name: 'Optimism', id: 'optimism' },
+              { name: 'Base', id: 'base' },
+              { name: 'Avalanche', id: 'avalanche' },
+            ].map((network) => (
+              <div key={network.id} className="p-3 rounded-lg bg-white/5 border border-white/10">
+                <p className="font-semibold text-emerald-400">{network.name}</p>
+                <p className="text-xs text-foreground/60">{network.id}</p>
+              </div>
+            ))}
+          </div>
+        </div>
+
+        <Callout type="info" title="Token List Updates">
+          The token list is automatically updated every 24 hours. For a fresh list, call the <code className="bg-black/40 px-2 py-1 rounded text-xs">refreshTokens()</code> method.
+        </Callout>
+
+        <div className="space-y-4">
+          <h2 className="text-2xl font-bold">Customizing Display</h2>
+          <CodeBlock
+            code={`// Hide tokens for a minimal display
+<WalletDisplay
+  address={address}
+  balance={balance}
+  network="ethereum"
+  showTokens={false}
+/>
+
+// Always show all tokens
+<WalletDisplay
+  address={address}
+  balance={balance}
+  network="ethereum"
+  showTokens={true}
+/>`}
+            language="tsx"
+          />
+        </div>
+      </div>
+    </>
+  )
+}