PROJECT OVERVIEW:
The project is to build a Single Page Application (SPA) that simplifies the process of creating responsive, email-safe HTML emails by allowing users to write content in Markdown. The core value proposition is to eliminate the complexity and frustration associated with traditional HTML email development, enabling users to focus on content creation rather than intricate markup. The application will provide an intuitive interface for writing, previewing, and exporting emails, making professional email communication accessible to a wider audience.
TECH STACK:
- Frontend Framework: React (using Vite for fast development setup)
- Styling: Tailwind CSS for utility-first styling and rapid UI development
- State Management: Zustand for efficient and simple global state management
- Markdown Parser: `marked` library for parsing Markdown to HTML
- HTML Sanitization: `dompurify` for security against XSS attacks
- Editor Component: `react-markdown` or a similar library for rendering Markdown within the editor, and potentially a more robust editor like CodeMirror or Monaco Editor if advanced features are desired later.
- Routing: React Router DOM for potential future multi-page functionality (though the MVP is SPA)
- Icons: Heroicons or similar for clean UI icons.
CORE FEATURES:
1. **Markdown Editor**:
* **User Flow**: User lands on the app, sees a split-screen view with a Markdown input area on one side and an HTML preview on the other. User types Markdown content into the input area. As they type, the preview updates in real-time.
* **Details**: The editor should support standard Markdown syntax (headings, lists, links, images, bold, italics). It should include basic formatting buttons (Bold, Italic, Link, Image) above the input area for quick access. A character/word count might be useful.
* **Security**: Ensure the editor input is handled securely to prevent injection attacks before parsing.
2. **Live HTML Preview**:
* **User Flow**: The preview pane dynamically renders the HTML output corresponding to the Markdown in the editor. This preview should accurately reflect how the email will look in a modern email client.
* **Details**: The preview needs to be 'email-safe', meaning it uses tables for layout and avoids modern CSS properties that might not be supported by all email clients. The `marked` library will convert Markdown to HTML, and then `dompurify` will sanitize it. Tailwind CSS will be used to style the preview, but critical styles will be inlined or defined in a way compatible with email clients.
* **Responsiveness**: The preview pane should simulate different screen sizes (desktop, mobile) to demonstrate responsiveness.
3. **Template Selection & Management**:
* **User Flow**: Users can select from a predefined list of templates (e.g., confirmation, welcome, newsletter). Selecting a template pre-populates the Markdown editor with the template's Markdown content.
* **Details**: The MVP will include 3-5 basic templates. Each template will have a corresponding Markdown file (`.md`) with frontmatter for metadata like `preheader` and `theme`. A template browser/selector component will display available templates visually or by name.
* **Data Model**: Templates stored as JSON objects or individual Markdown files, potentially loaded from a local JSON or directly from the `/templates` directory.
4. **HTML Export**:
* **User Flow**: A button is available to export the generated HTML. Clicking this button either copies the HTML to the clipboard or opens it in a new tab, or provides a download link.
* **Details**: The exported HTML should be clean, well-formatted, and include inlined CSS where necessary for maximum compatibility. It should also include the necessary `DOCTYPE` and basic `<html>`, `<head>`, and `<body>` tags suitable for email.
5. **User Authentication & Persistence (Future/Optional for MVP but good to consider)**:
* **User Flow**: Users can sign up/log in. Saved templates and user preferences are stored and accessible across sessions.
* **Details**: For MVP, local storage might suffice for saving unsaved drafts. Full authentication (e.g., Firebase Auth, Supabase) would be for later phases.
UI/UX DESIGN:
- **Layout**: A two-column layout for the editor and preview. The editor column takes up 50% of the width, and the preview column takes the other 50%. This layout should be fully responsive, collapsing to a single column on smaller screens (e.g., mobile).
- **Color Palette**: A clean, professional palette. Primary: `#4A90E2` (Blue), Secondary: `#F5A623` (Orange/Yellow for CTAs), Accent: `#50E3C2` (Teal/Green for success states), Neutral: `#FFFFFF`, `#F8F9FA` (Light Gray), `#212529` (Dark Gray/Black for text). Dark mode option for the editor using the `theme: dark` frontmatter.
- **Typography**: Use a clean, readable sans-serif font like 'Inter' or 'Inter Variable' for UI elements and content. Markdown headings should be distinct. Use Tailwind's typography plugin for Markdown content styling.
- **Responsive Design**: Mobile-first approach. Main layout adjusts. Navigation (if any) becomes a hamburger menu. Buttons and interactive elements are easily tappable on touch devices. Ensure preview renders correctly on various device widths.
- **Components**: Clear visual hierarchy. Use cards for templates. Prominent buttons for actions like Export. Subtle loading indicators.
COMPONENT BREAKDOWN:
- `App.jsx`: Main application component, sets up layout and state.
- `EditorPane.jsx`: Contains the Markdown input area and formatting toolbar. Receives `markdownContent` and `setMarkdownContent` as props.
- `PreviewPane.jsx`: Renders the live HTML preview. Receives `htmlContent` as a prop.
- `TemplateSelector.jsx`: Displays available templates and handles selection. Receives `onSelectTemplate` and `templates` as props.
- `Toolbar.jsx`: Component for formatting buttons (Bold, Italic, Link, etc.) within the `EditorPane`.
- `TemplateCard.jsx`: Displays a single template in the `TemplateSelector`. Receives `template` object and `onClick` handler.
- `Layout.jsx`: Main structural component defining the two-column layout, responsive adjustments, and possibly header/footer.
- `Header.jsx`: Application header with logo and possibly user authentication links (future).
- `Footer.jsx`: Application footer with copyright and links.
- `useEmailMD.js` (Zustand store): Manages `markdownContent`, `htmlContent`, `selectedTemplate`, `templates`, `isLoading`, `errorState`.
DATA MODEL:
- **State**: Managed by Zustand store.
- `markdownContent`: string (current Markdown input)
- `htmlContent`: string (generated HTML for preview)
- `sanitizedHtmlContent`: string (final HTML for export, after sanitization)
- `selectedTemplate`: object/null (the currently selected template)
- `templates`: array of objects (list of available templates)
- `isLoading`: boolean (for export or processing)
- `errorState`: object/string/null (for handling errors)
- `previewMode`: 'desktop' | 'mobile' | 'tablet' (for responsive preview)
- **Template Object Structure**: `{ id: string, name: string, markdown: string, frontmatter: { preheader?: string, theme?: 'dark' | 'light' } }`
- **Mock Data**: `templates` array will be populated with mock data initially. `markdownContent` will have initial example text.
ANIMATIONS & INTERACTIONS:
- **Editor/Preview Splitter**: Smooth resizing of the editor and preview panes using a draggable splitter.
- **Hover Effects**: Subtle background color changes on buttons and template cards on hover.
- **Transition Animations**: Smooth transitions for opening/closing sidebars (if any), changing preview modes, or showing/hiding loading indicators.
- **Loading States**: Use spinners or skeleton loaders when processing Markdown to HTML or exporting. Display a clear `isLoading` state.
- **Micro-interactions**: Button press feedback, smooth scrolling between editor and preview. Real-time update should feel instantaneous.
EDGE CASES:
- **Empty Markdown**: Handle empty `markdownContent`. Preview should show a default empty state or message. Export should produce minimal valid HTML.
- **Invalid Markdown/HTML**: The `marked` parser should gracefully handle malformed Markdown. `dompurify` should block any malicious attempts.
- **Large Content**: Ensure performance is maintained even with very long Markdown inputs. Consider debouncing input updates for the preview.
- **Browser Compatibility**: Test thoroughly across major browsers (Chrome, Firefox, Safari, Edge).
- **Email Client Compatibility**: While the goal is 'email-safe', specific rendering issues might arise. The preview should be as accurate as possible. Document known limitations.
- **Error Handling**: Display user-friendly error messages for parsing failures, export issues, or network errors (if applicable later).
- **Accessibility (a11y)**: Ensure all interactive elements have proper ARIA attributes, keyboard navigation is supported, and sufficient color contrast is maintained. Use semantic HTML where possible.
SAMPLE DATA:
```json
[
{
"id": "confirm-email",
"name": "Email Confirmation",
"markdown": `---\npreheader: "Confirm your email address"
theme: dark
---::: header {width=\"200\"} :::# Confirm your email address\n\nYour confirmation code is below - enter it in your open browser window and we\'ll help you get signed in.::: callout center compact # DFY-X7U :::If you didn\'t request this email, there\'s nothing to worry about, you can safely ignore it.::: footer Acme Inc. | 123 Main St [Unsubscribe](https://example.com/unsub) :::",
"frontmatter": {
"preheader": "Confirm your email address",
"theme": "dark"
}
},
{
"id": "welcome-message",
"name": "Welcome Message",
"markdown": `---\npreheader: "Welcome to Our Service!"
theme: light
---::: header {width=\"200\"} :::# Welcome aboard, [User Name]!\n\nWe\'re thrilled to have you join our community. Get started by exploring our features:\n\n* Feature 1\n* Feature 2\n* Feature 3::: callout primary "Get Started"(https://example.com/get-started):::::: footer Acme Inc. | Thank you for joining! :::",
"frontmatter": {
"preheader": "Welcome to Our Service!",
"theme": "light"
}
},
{
"id": "newsletter-basic",
"name": "Basic Newsletter",
"markdown": `---\npreheader: "Your Weekly Update is Here!"
theme: light
---::: header {width=\"200\"} :::# This Week\'s Highlights\n\n**What\'s new?**\n\n- Exciting announcement A\n- Interesting article B\n\n[Read More](https://example.com/blog)::: footer Acme Inc. | Stay updated! [Unsubscribe](https://example.com/unsub) :::",
"frontmatter": {
"preheader": "Your Weekly Update is Here!",
"theme": "light"
}
}
]
```
Initial `markdownContent` state could be the markdown from the `confirm-email` template.
DEPLOYMENT NOTES:
- **Build Tool**: Vite is recommended for its speed. `npm run build` command will generate optimized static assets in a `dist` folder.
- **Environment Variables**: Use `.env` files for any configuration (e.g., API keys if added later). Vite uses `VITE_` prefix for environment variables exposed to the client.
- **Performance Optimizations**: Code splitting (if app grows), image optimization (use appropriate formats and sizes), lazy loading components. Minify CSS and JavaScript in the production build.
- **Hosting**: Deploy to static hosting platforms like Vercel, Netlify, or GitHub Pages for cost-effectiveness and scalability.
- **HTTPS**: Ensure the deployment uses HTTPS for security.
- **CORS**: If an API is introduced later, ensure proper CORS configuration on the backend.
- **SEO**: Add meta tags for the landing page if it's not purely an application shell. Use `react-helmet-async` for managing head tags.
- **Domain**: Configure a custom domain for the deployed application.