@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

npm install @rajkrajpj/cultivate-ui-library

Basic Setup

1. Import styles in your app entry point:

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

2. Configure Tailwind CSS:

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

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:

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

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

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

📚 API Reference

Core Props

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

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 - Comprehensive implementation guides
• Architecture Plan - Technical architecture and design
• Live Examples - Interactive code examples

🚢 Migration Benefits

Before (Legacy):

// ~500+ lines of custom form code
// Manual step management
// Custom validation logic
// Manual persistence
// Regulation-specific hardcoding

After (Library):

// ~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 for details.

Ready to build investor forms in minutes? Check out the examples to see the library in action!