@bernierllc/email-ui/README.md

React UI components for email management, templates, scheduling, and analytics

# @bernierllc/email-ui

React UI components for email management, templates, scheduling, and analytics.

## Installation

```bash
npm install @bernierllc/email-ui
```

## Usage

```typescript
import { TemplateEditor, EmailComposer, AnalyticsDashboard } from '@bernierllc/email-ui';

// Basic template editor
<TemplateEditor
  onSave={handleSaveTemplate}
  onCancel={() => setEditing(false)}
/>

// Email composer with scheduling
<EmailComposer
  templates={templates}
  onSend={handleSendEmail}
  onSchedule={handleScheduleEmail}
  onSaveDraft={handleSaveDraft}
/>

// Analytics dashboard
<AnalyticsDashboard
  analytics={analyticsData}
  onRefresh={handleRefresh}
  onExport={handleExport}
/>
```

## Components

### TemplateEditor

Full-featured email template editor with variable detection and preview mode.

#### Props

- `template?: Partial<EmailTemplate>` - Existing template to edit
- `onSave: (template: TemplateFormData) => Promise<void>` - Save handler
- `onCancel?: () => void` - Cancel handler
- `isLoading?: boolean` - Loading state
- `className?: string` - Custom CSS class
- `style?: React.CSSProperties` - Inline styles

#### Features

- Variable extraction from content (`{{variable}}` syntax)
- Live preview mode
- Form validation
- Category and tag management

### EmailComposer

Comprehensive email composition interface with template integration.

#### Props

- `templates?: EmailTemplate[]` - Available templates
- `onSend: (email: EmailComposition) => Promise<void>` - Send handler
- `onSchedule?: (email: EmailComposition) => Promise<void>` - Schedule handler
- `onSaveDraft?: (email: Partial<EmailComposition>) => Promise<void>` - Draft handler
- `isLoading?: boolean` - Loading state
- `className?: string` - Custom CSS class
- `style?: React.CSSProperties` - Inline styles

#### Features

- Template selection and variable population
- File attachments
- Email scheduling
- Draft saving
- Form validation

### AnalyticsDashboard

Comprehensive email analytics visualization with multiple view modes.

#### Props

- `analytics: EmailAnalytics[]` - Analytics data array
- `isLoading?: boolean` - Loading state
- `onRefresh?: () => Promise<void>` - Refresh handler
- `onExport?: (format: 'csv' | 'pdf') => Promise<void>` - Export handler
- `className?: string` - Custom CSS class
- `style?: React.CSSProperties` - Inline styles

#### Features

- Overview metrics with calculated rates
- Trends visualization
- Detailed breakdown tables
- Export functionality
- Multiple view modes

## API Reference

## Type Definitions

### EmailTemplate
```typescript
interface EmailTemplate {
  id: string;
  name: string;
  subject: string;
  content: string;
  variables: string[];
  category?: string;
  tags?: string[];
  createdAt: Date;
  updatedAt: Date;
  isActive: boolean;
}
```

### EmailComposition
```typescript
interface EmailComposition {
  to: string[];
  cc?: string[];
  bcc?: string[];
  subject: string;
  content: string;
  templateId?: string;
  variables?: Record<string, any>;
  attachments?: File[];
  scheduleTime?: Date;
}
```

### EmailAnalytics
```typescript
interface EmailAnalytics {
  templateId?: string;
  sent: number;
  delivered: number;
  opened: number;
  clicked: number;
  bounced: number;
  complained: number;
  openRate: number;
  clickRate: number;
  bounceRate: number;
  period: {
    start: Date;
    end: Date;
  };
}
```

## Integration

### Logger Integration

Components support optional logger integration for debugging and monitoring:

```typescript
import { Logger } from '@bernierllc/logger';

const logger = new Logger({ service: 'email-ui' });

// Components automatically detect and use logger when available
<TemplateEditor onSave={handleSave} />
```

**Integration Status**: ✅ **Ready** - Components automatically detect logger presence and provide enhanced debugging capabilities including:
- Component lifecycle logging
- User interaction tracking  
- Error reporting and debugging
- Performance monitoring

### NeverHub Integration

Components support optional NeverHub integration for enhanced functionality:

```typescript
import { NeverHubAdapter } from '@bernierllc/neverhub-adapter';

// Components automatically detect NeverHub presence
// and enable enhanced capabilities when available
```

**Integration Status**: ✅ **Ready** - Components automatically detect NeverHub availability and enable:
- Real-time email event notifications
- Cross-component state synchronization
- Enhanced metrics collection
- Distributed debugging and monitoring

### Integration Documentation

This package follows the **graceful degradation** pattern:
- All components work independently without any integrations
- Logger integration adds debugging and monitoring capabilities  
- NeverHub integration adds real-time and distributed features
- No breaking changes when integrations are added or removed

## Security

### Input Sanitization

All user inputs are properly sanitized:
- Email addresses validated with RFC-compliant patterns
- HTML content sanitized to prevent XSS attacks
- File uploads validated for type and size
- Template variables escaped to prevent injection

### Content Security Policy

Components are designed to work with strict CSP:
- No inline styles or scripts
- All dynamic content properly escaped
- External resource loading controlled
- Event handlers use proper event delegation

### Data Protection

Components handle sensitive data securely:
- Email content encrypted in transit
- Temporary files cleaned up automatically  
- No sensitive data stored in browser storage
- Audit logging for security events (when logger integration enabled)

## Styling

Components use BEM CSS methodology for consistent styling:

```css
.email-composer {
  /* Component root */
}

.email-composer__header {
  /* Component header */
}

.email-composer__form {
  /* Form container */
}

.form-group {
  /* Form field group */
}

.form-input {
  /* Input fields */
}

.btn {
  /* Base button styles */
}

.btn--primary {
  /* Primary button variant */
}

.btn--secondary {
  /* Secondary button variant */
}
```

## Development

### Building

```bash
npm run build
```

### Testing

```bash
npm test
npm run test:coverage
npm run test:watch
```

### Linting

```bash
npm run lint
npm run lint:fix
```

## Dependencies

- React 18+
- Zod for validation
- DOM APIs for browser functionality

## License

Copyright (c) 2025 Bernier LLC. All rights reserved.

This package is licensed under the Bernier LLC license. See LICENSE file for details.

## Support

For support and questions, please contact Bernier LLC or refer to the project documentation.