@rajkrajpj/cultivate-ui-library/README.md

A modern, type-safe, accessible React component library for fintech investor forms. Build complete investor forms in minutes with zero configuration, supporting multiple regulations (RegA+, RegD, RegCF) and investor types.

# @rajkrajpj/cultivate-ui-library

A modern, type-safe, accessible React component library for fintech investor forms. Build complete investor forms in minutes with zero configuration, supporting multiple regulations (RegA+, RegD, RegCF) and investor types.

## ✨ Features

- **Zero Configuration**: Complete investor form in ~25 lines of code
- **Multi-Regulation Support**: RegA+, RegD, RegCF with built-in compliance
- **Multiple Investor Types**: Individual, Joint, Company, Trust, IRA
- **Type-Safe**: Full TypeScript support with comprehensive types
- **Production Ready**: Validation, persistence, error handling built-in
- **Accessible**: WCAG 2.1 AA compliance out of the box
- **Mobile Optimized**: Responsive design for all devices

## 🚀 Quick Start

### Installation

```bash
npm install @rajkrajpj/cultivate-ui-library
```

### Basic Setup

1. **Import styles** in your app entry point:

```tsx
import "@rajkrajpj/cultivate-ui-library/styles"
```

2. **Configure Tailwind CSS**:

```js
// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@rajkrajpj/cultivate-ui-library/**/*.{js,ts,jsx,tsx}",
  ],
  // ...rest of your config
}
```

3. **Create your investor form**:

```tsx
import {
  createDefaultSteps,
  InvestorFormData,
  InvestorFormWizard,
} from "@rajkrajpj/cultivate-ui-library"

export default function MyInvestorForm() {
  // Define your offering parameters
  const offeringParams = {
    offeringId: "my-offering-123",
    companyName: "My Startup Inc",
    sharePrice: 10,
    minInvestment: 100,
    maxInvestment: 10000,
    deadline: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
    regulation: "regA",
  }

  // Zero configuration - uses all sensible defaults
  const steps = createDefaultSteps({
    regulation: offeringParams.regulation,
  })

  const handleComplete = async (formData: Partial<InvestorFormData>) => {
    // Submit to your API
    await fetch("/api/investments", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(formData),
    })
    console.log("Investment submitted successfully!")
  }

  return (
    <div className="max-w-md mx-auto p-8">
      <InvestorFormWizard<InvestorFormData>
        steps={steps}
        regulation={offeringParams.regulation}
        offeringParams={offeringParams}
        onComplete={handleComplete}
      />
    </div>
  )
}
```

That's it! You now have a complete 12-step investor form with validation, persistence, and regulation compliance.

## 📋 Form Steps Included

The library provides a complete investor onboarding flow:

1. **Get Started** - Email, name collection
2. **Select Investor Type** - Individual, Joint, Company, Trust/IRA
3. **Personal Information** - Personal details based on type
4. **Address Information** - Address collection with validation
5. **Identity Information** - SSN, DOB, identity verification
6. **Investment Amount** - Amount selection with share calculation
7. **Self Accreditation** - Accreditation verification (if required)
8. **Unaccredited Investor** - Income/net worth (conditional)
9. **Acknowledgement** - Agreements and certifications
10. **Payment Selection** - Payment method selection
11. **Payments** - Payment processing
12. **Success** - Confirmation page

## 🎯 Advanced Usage

### Custom Step Handlers

For production applications requiring API integration at each step:

```tsx
import { StepHandlers } from "@rajkrajpj/cultivate-ui-library"

const stepHandlers: StepHandlers = {
  onGetStartedSubmit: async (data) => {
    // Save lead immediately
    await fetch("/api/leads", {
      method: "POST",
      body: JSON.stringify({
        email: data.email,
        firstName: data.firstName,
        lastName: data.lastName,
      }),
    })
  },
  onInvestmentAmountSubmit: async (data) => {
    // Validate investment limits
    await fetch("/api/validate-investment", {
      method: "POST",
      body: JSON.stringify({
        amount: data.investmentAmount,
        investorType: data.investorType,
      }),
    })
  },
  onIdentityInfoSubmit: async (data) => {
    // Submit KYC verification
    await fetch("/api/kyc-verification", {
      method: "POST",
      body: JSON.stringify({
        ssn: data.ssn,
        birthDate: data.birthDate,
        address: data.address,
      }),
    })
  },
}

const steps = createDefaultSteps({
  regulation: "regCF",
  enableDebugLogs: process.env.NODE_ENV === "development",
  stepHandlers,
  customSuccessHandler: () => {
    window.location.href = "/investment-success"
  },
})
```

### Form Persistence & Error Handling

```tsx
<InvestorFormWizard
  steps={steps}
  regulation="regA"
  offeringParams={offeringParams}
  persistenceKey="investor-form-draft" // Auto-saves to localStorage
  onError={(error, stepId) => {
    console.error(`Error in step ${stepId}:`, error)
  }}
  onComplete={handleComplete}
/>
```

## 🎨 Theming

### Custom Colors

Override CSS variables for custom branding:

```css
:root {
  --primary: #0066cc;
  --primary-foreground: #ffffff;
  --secondary: #6b7280;
  --background: #f9fafb;
  --border: #e5e7eb;
  --input: #ffffff;
  --ring: #0066cc;
}
```

## 📚 API Reference

### Core Props

```tsx
interface InvestorFormWizardProps<T> {
  steps: StepConfig<T>[]                    // Step configurations
  regulation: "regA" | "regD" | "regCF"     // Regulation type
  offeringParams?: OfferingParams           // Offering details
  onComplete?: (data: Partial<T>) => Promise<void>  // Form completion
  onError?: (error: Error, step: string) => void    // Error handling
  persistenceKey?: string                   // Auto-save key
  initialData?: Partial<T>                  // Pre-populate data
}
```

### Offering Parameters

```tsx
interface OfferingParams {
  offeringId: string      // Unique identifier
  companyName: string     // Display name
  sharePrice: number      // Price per share
  minInvestment: number   // Minimum amount
  maxInvestment: number   // Maximum amount
  deadline: Date          // Offering deadline
  regulation: string      // Regulation type
}
```

## 🔧 Regulation Support

### RegA+ (Regulation A+)
- Supports accredited and unaccredited investors
- Investment limits for unaccredited investors
- Comprehensive KYC requirements

### RegCF (Regulation Crowdfunding)  
- Shows agreement checkbox for guest flows
- Annual investment limits based on income/net worth
- Simplified onboarding process

### RegD (Regulation D)
- Requires accreditation verification
- No investment limits for accredited investors
- Enhanced due diligence requirements

## 📖 Documentation & Examples

- **[Usage Examples](https://github.com/jacksiconvalley/cultivate-ui-library/blob/main/dev-docs/library-usage-examples.md)** - Comprehensive implementation guides
- **[Architecture Plan](https://github.com/jacksiconvalley/cultivate-ui-library/blob/main/dev-docs/investor-forms-library-plan.md)** - Technical architecture and design
- **[Live Examples](https://github.com/jacksiconvalley/cultivate-ui-library/tree/main/src/examples)** - Interactive code examples

## 🚢 Migration Benefits

**Before (Legacy):**
```tsx
// ~500+ lines of custom form code
// Manual step management
// Custom validation logic
// Manual persistence
// Regulation-specific hardcoding
```

**After (Library):**
```tsx
// ~25 lines of business logic
const steps = createDefaultSteps({ regulation: "regA" })
return <InvestorFormWizard steps={steps} onComplete={handleSubmit} />
```

**Key Benefits:**
- 90%+ reduction in boilerplate code
- Built-in compliance and validation
- Production-ready components
- Type-safe development experience
- Consistent UX across all forms

## 📄 License

MIT License - see [LICENSE](./LICENSE) for details.

---

**Ready to build investor forms in minutes?** Check out the [examples](https://github.com/jacksiconvalley/cultivate-ui-library/tree/main/src/examples) to see the library in action!