Build fixes, email preview system

2025-12-15 10:34:43 -05:00 · 2025-07-29 19:45:38 -04:00
parent e6791f8cb8
commit 9370d5c935
78 changed files with 5798 additions and 10397 deletions
--- a/docs/email-features.md
+++ b/docs/email-features.md
@@ -0,0 +1,281 @@
+# Enhanced Email Sending Features
+
+## Overview
+
+The beenvoice application now includes a comprehensive email sending system with preview, rich text editing, and confirmation features. This enhancement provides a professional email experience for sending invoices to clients.
+
+## Features
+
+### 🎨 Rich Text Email Composer
+- **Tiptap Editor Integration**: Professional rich text editing with formatting options
+- **Text Formatting**: Bold, italic, strikethrough, and color options
+- **Text Alignment**: Left, center, and right alignment
+- **Lists**: Bullet points and numbered lists
+- **Color Picker**: Choose from a variety of text colors
+- **Real-time Preview**: See changes as you type
+
+### 👁️ Email Preview
+- **Visual Preview**: See exactly how your email will appear to recipients
+- **Invoice Summary**: Displays key invoice details (number, date, amount)
+- **Attachment Notice**: Shows PDF attachment information
+- **Professional Styling**: Clean, branded email template
+- **Responsive Design**: Optimized for all screen sizes with proper text wrapping
+- **Mobile-First**: Touch-friendly interface with proper spacing
+
+### ✅ Send Confirmation
+- **Two-Step Process**: Compose ↔ Preview with Send Action
+- **Action-Based Sending**: Send button available from sidebar and floating action bar
+- **Status Updates**: Automatic status change from draft to sent
+- **Error Handling**: Clear error messages with specific guidance
+- **SSR Compatible**: Proper hydration handling for server-side rendering
+
+### 📄 Smart Templates
+- **Auto-Generated Content**: Professional email templates with proper paragraph spacing
+- **Time-Based Greetings**: Morning, afternoon, or evening greetings
+- **Invoice Details**: Automatically includes invoice number, date, and amount
+- **Business Branding**: Uses your business name and contact information
+- **Immediate Loading**: Content appears instantly in the editor without requiring tab switching
+
+## Components
+
+### EmailComposer
+**Location**: `src/components/forms/email-composer.tsx`
+
+A rich text editor component for composing emails with formatting options.
+
+**Props**:
+- `subject`: Email subject line
+- `onSubjectChange`: Callback for subject changes
+- `content`: Email content (HTML)
+- `onContentChange`: Callback for content changes
+- `fromEmail`: Sender email address
+- `toEmail`: Recipient email address
+
+### EmailPreview
+**Location**: `src/components/forms/email-preview.tsx`
+
+Displays a visual preview of how the email will appear to recipients.
+
+**Props**:
+- `subject`: Email subject line
+- `fromEmail`: Sender email address
+- `toEmail`: Recipient email address
+- `content`: Email content (HTML)
+- `invoice`: Invoice data for summary display
+
+### SendEmailDialog
+**Location**: `src/components/forms/send-email-dialog.tsx`
+
+Main dialog component that combines composition, preview, and confirmation.
+
+**Props**:
+- `invoiceId`: ID of the invoice to send
+- `trigger`: React element that opens the dialog
+- `invoice`: Invoice data
+- `onEmailSent`: Callback when email is successfully sent
+
+### EnhancedSendInvoiceButton
+**Location**: `src/components/forms/enhanced-send-invoice-button.tsx`
+
+Enhanced button component that opens the email dialog.
+
+**Props**:
+- `invoiceId`: ID of the invoice to send
+- `variant`: Button style variant
+- `className`: Additional CSS classes
+- `showResend`: Whether to show "Resend" text
+- `size`: Button size
+
+## API Enhancements
+
+### Enhanced Email Router
+**Location**: `src/server/api/routers/email.ts`
+
+The email API has been enhanced to support custom content and HTML emails.
+
+**New Parameters**:
+- `customSubject`: Optional custom email subject
+- `customContent`: Optional custom email content (HTML)
+- `useHtml`: Boolean flag to send HTML email
+
+**Features**:
+- HTML email support with plain text fallback
+- Custom subject lines
+- Rich HTML content
+- Automatic PDF attachment
+- BCC to business email
+- Comprehensive error handling
+
+## Usage Examples
+
+### Basic Usage
+```tsx
+import { EnhancedSendInvoiceButton } from "~/components/forms/enhanced-send-invoice-button";
+
+// Replace existing send buttons
+<EnhancedSendInvoiceButton
+  invoiceId={invoice.id}
+  className="w-full"
+  showResend={invoice.status === "sent"}
+/>
+```
+
+### Custom Dialog
+```tsx
+import { SendEmailDialog } from "~/components/forms/send-email-dialog";
+
+<SendEmailDialog
+  invoiceId={invoice.id}
+  invoice={invoiceData}
+  trigger={<Button>Send Custom Email</Button>}
+  onEmailSent={() => console.log("Email sent!")}
+/>
+```
+
+### Standalone Components
+```tsx
+import { EmailComposer } from "~/components/forms/email-composer";
+import { EmailPreview } from "~/components/forms/email-preview";
+
+// Use individual components for custom implementations
+<EmailComposer
+  subject={subject}
+  onSubjectChange={setSubject}
+  content={content}
+  onContentChange={setContent}
+  fromEmail="you@business.com"
+  toEmail="client@company.com"
+/>
+
+<EmailPreview
+  subject={subject}
+  content={content}
+  fromEmail="you@business.com"
+  toEmail="client@company.com"
+  invoice={invoiceData}
+/>
+```
+
+## Technical Details
+
+### Dependencies
+- **@tiptap/react**: Rich text editor framework
+- **@tiptap/starter-kit**: Basic editor functionality
+- **@tiptap/extension-text-style**: Text styling support
+- **@tiptap/extension-color**: Color picker support
+- **@tiptap/extension-text-align**: Text alignment options
+
+### Email Templates
+The system generates professional HTML email templates with:
+- Responsive design
+- Brand colors (green theme)
+- Invoice summary cards
+- Proper typography
+- Attachment indicators
+- Footer branding
+
+### Error Handling
+Comprehensive error handling for:
+- Invalid email addresses
+- Missing client information
+- Resend API issues
+- Network connectivity problems
+- Domain verification issues
+- Rate limiting
+
+## Usage in Application
+
+The enhanced email functionality is integrated throughout the application:
+- Invoice view pages with enhanced send buttons
+- Full-page email composition interface
+- Professional email templates with invoice integration
+- Comprehensive preview and confirmation workflow
+
+## Migration Guide
+
+### From Basic Send Button
+Replace existing `SendInvoiceButton` components with `EnhancedSendInvoiceButton`:
+
+```tsx
+// Before
+import { SendInvoiceButton } from "../_components/send-invoice-button";
+<SendInvoiceButton invoiceId={invoice.id} />
+
+// After
+import { EnhancedSendInvoiceButton } from "~/components/forms/enhanced-send-invoice-button";
+<EnhancedSendInvoiceButton invoiceId={invoice.id} />
+```
+
+### API Compatibility
+The enhanced email API is backward compatible with existing implementations. New features are opt-in through additional parameters.
+
+## Security Considerations
+
+- **Input Sanitization**: All user input is validated and sanitized
+- **Email Validation**: Comprehensive email format validation
+- **Rate Limiting**: Built-in protection against spam
+- **Domain Verification**: Resend domain verification required
+- **Authentication**: All email operations require valid authentication
+
+## Performance
+
+- **SSR Optimization**: Proper server-side rendering with hydration safeguards
+- **Efficient Loading**: Content initializes immediately without requiring user interaction
+- **Optimized Rendering**: Efficient React component updates with proper state management
+- **Caching**: Proper query caching for invoice data
+- **Error Boundaries**: Graceful error handling without crashes
+- **Responsive Design**: Optimized layouts for all screen sizes with text overflow prevention
+
+## Navigation
+
+### Send Email Page
+Access the email interface by clicking "Send Invoice" on any invoice:
+- `/dashboard/invoices/[id]/send` - Full-page email composition
+- Two-tab interface: Compose ↔ Preview
+- Send action available from sidebar and floating action bar
+- Fully responsive design with proper text wrapping and overflow handling
+- Professional layout with sidebar containing:
+  - Invoice summary (number, client, date, status)
+  - Email details (from, to, subject, attachment info)
+  - Context-aware action buttons
+- Auto-filled message with proper HTML formatting and paragraph spacing
+- Immediate content loading without requiring tab navigation
+
+## Fixes and Improvements
+
+Recent fixes and enhancements:
+- **SSR Compatibility**: Fixed Tiptap hydration issues for reliable server-side rendering
+- **Content Loading**: Improved email content initialization for immediate display
+- **Responsive Design**: Enhanced text wrapping and overflow handling for all screen sizes
+- **UI/UX**: Removed confirmation tab in favor of action-based sending approach
+- **Performance**: Optimized state management for faster content loading
+
+## Future Enhancements
+
+Planned improvements include:
+- Email templates library
+- Scheduling email delivery
+- Email tracking and read receipts
+- Bulk email sending
+- Custom email signatures
+- Integration with email marketing tools
+
+## Support
+
+For issues or questions related to the email system:
+1. Check the console for error messages
+2. Verify Resend API configuration
+3. Ensure client email addresses are valid
+4. Review domain verification status
+5. Check network connectivity
+
+## Changelog
+
+### Version 1.0.0
+- Initial release of enhanced email system
+- Rich text editor integration
+- Email preview functionality
+- Send confirmation workflow
+- HTML email support
+- Professional templates
+- Demo page implementation