feat: implement invoice submission form for NFT minting #186

demo-invoice-form.md

@@ -0,0 +1,161 @@
+# Invoice Submission Form - Implementation Demo
+
+## Overview
+The enhanced `InvoiceMintForm` component now provides a comprehensive invoice submission interface for NFT minting with the following improvements:
+
+## ✅ Implemented Features
+
+### 1. **Enhanced Form Fields**
+- **Debtor Name**: Required field with validation (2-100 characters)
+- **Invoice Amount**: Number input with strict validation ($0.01 - $1,000,000)
+- **Due Date**: Date picker with future date validation
+- **Invoice Document**: PDF file upload (max 5MB)
+- **Supporting Document URI**: Optional URL field for additional documentation
+
+### 2. **Advanced Validation & Sanitization**
+```typescript
+// Input sanitization removes dangerous characters
+const sanitizeString = (str: string) => str.trim().replace(/[<>"'&]/g, '');
+
+// Zod schema with comprehensive validation
+const invoiceSchema = z.object({
+  debtorName: z.string().min(2).max(100).transform(sanitizeString),
+  amount: z.number().min(0.01).max(1000000),
+  dueDate: z.string().refine(date => new Date(date) > today),
+  // ... additional validations
+});
+```
+
+### 3. **Real-time Fee Calculation**
+- **Network Fee**: ~$0.001 (0.01 XLM at $0.10/XLM)
+- **Protocol Fee**: 0.5% of invoice amount
+- **Total Fee**: Dynamically calculated and displayed
+
+### 4. **Enhanced Soroban Integration**
+```typescript
+export interface InvoiceMetadata {
+  debtorName: string;
+  dueDate: string;
+  supportingDocumentUri: string | null;
+  timestamp: number;
+}
+
+export interface MintInvoiceParams {
+  invoiceId: string;
+  amount: bigint;
+  recipient: string;
+  callerPublicKey: string;
+  metadata?: InvoiceMetadata; // New metadata support
+}
+```
+
+### 5. **Improved User Experience**
+- Better visual hierarchy and spacing
+- Clear field indicators (required vs optional)
+- Real-time validation feedback
+- Loading states during submission
+- Comprehensive error handling
+
+## 🔧 Technical Implementation
+
+### Form State Management
+```typescript
+const {
+  register,
+  handleSubmit,
+  formState: { errors, isSubmitting },
+  setValue,
+  watch,
+  reset,
+} = useForm<InvoiceFormData>({
+  resolver: zodResolver(invoiceSchema),
+});
+```
+
+### Fee Calculation Logic
+```typescript
+useEffect(() => {
+  if (watchedAmount && watchedAmount > 0) {
+    const networkFeeXLM = 0.01;
+    const xlmPrice = 0.10;
+    const networkFeeUSD = networkFeeXLM * xlmPrice;
+    const protocolFee = watchedAmount * 0.005; // 0.5%
+
+    setFeeEstimate({
+      networkFee: networkFeeUSD,
+      protocolFee: protocolFee,
+      totalFee: networkFeeUSD + protocolFee
+    });
+  }
+}, [watchedAmount]);
+```
+
+### Contract Payload Formatting
+```typescript
+const formatContractPayload = (data: InvoiceFormData) => {
+  const publicKey = (session?.user as any)?.publicKey;
+  const amountInStroops = BigInt(Math.round(data.amount * 10_000_000));
+  const invoiceId = `INV-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+  return {
+    invoiceId,
+    amount: amountInStroops,
+    recipient: publicKey,
+    callerPublicKey: publicKey,
+    metadata: {
+      debtorName: data.debtorName,
+      dueDate: data.dueDate,
+      supportingDocumentUri: data.supportingDocumentUri || null,
+      timestamp: Date.now()
+    }
+  };
+};
+```
+
+## 📋 Validation Rules
+
+| Field | Validation | Error Message |
+|-------|------------|---------------|
+| Debtor Name | 2-100 chars, sanitized | "Debtor name must be at least 2 characters" |
+| Amount | 0.01-1,000,000 USD | "Amount must be greater than 0" |
+| Due Date | Future dates only | "Due date must be in the future" |
+| Invoice File | PDF, max 5MB | "Only PDF files are allowed" |
+| Supporting URI | Valid URL format | "Must be a valid URL" |
+
+## 🎯 Acceptance Criteria Met
+
+✅ **Multi-step comprehensive form** - All required fields implemented  
+✅ **Client-side validation** - Strict validation with sanitization  
+✅ **Fee calculation and display** - Real-time network + protocol fees  
+✅ **Soroban payload formatting** - Perfect contract integration  
+✅ **react-hook-form + zod** - Form state and validation schema  
+✅ **Input sanitization** - Security-focused data cleaning  
+
+## 🚀 Usage Example
+
+```tsx
+import InvoiceMintForm from '@/components/InvoiceMintForm';
+
+function InvoiceSubmission() {
+  const handleSuccess = (txStatus: string) => {
+    console.log('Transaction successful:', txStatus);
+  };
+
+  return (
+    <InvoiceMintForm
+      onClose={() => console.log('Form closed')}
+      onSuccess={handleSuccess}
+    />
+  );
+}
+```
+
+## 🔍 Key Improvements
+
+1. **Security**: Input sanitization prevents XSS attacks
+2. **UX**: Real-time fee transparency
+3. **Validation**: Comprehensive client-side checks
+4. **Integration**: Enhanced Soroban contract support
+5. **Accessibility**: Proper form labels and error messages
+
+The form now provides a production-ready interface for businesses to submit invoices for NFT minting with full validation, fee transparency, and seamless blockchain integration.