payload-plugin-newsletter 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,3 +1,43 @@
+## [0.20.0] - 2025-07-31
+
+### Added
+- **Email Preview Customization** - Full control over email preview rendering
+  - New `emailPreview` customization options in `BroadcastCustomizations` interface
+  - `wrapInTemplate` option to disable default email template wrapping
+  - `customWrapper` function for custom email template wrappers
+  - Support for both sync and async custom wrapper functions
+  - Pass subject and preheader to custom wrapper for complete control
+  - `customPreviewComponent` option (planned) for replacing the entire preview component
+
+### Enhanced
+- **Plugin Configuration Context**
+  - Added `PluginConfigContext` for passing configuration throughout component tree
+  - `usePluginConfig` hook for required config access
+  - `usePluginConfigOptional` hook for safe optional config access
+  - Context provider integration in component hierarchy
+
+- **Email Preview Component**
+  - Updated to respect email preview customization options
+  - Backward compatible with default template wrapping behavior
+  - Support for both prop-based and context-based config passing
+  - Seamless integration with custom wrapper functions
+
+- **Preview Endpoint**
+  - Updated to use email preview customization options
+  - Consistent behavior between UI preview and API preview
+  - Maintains all existing functionality while adding customization
+
+### Technical Improvements
+- **Type Safety** - Full TypeScript support for all customization options
+- **Backward Compatibility** - All changes maintain 100% backward compatibility
+- **Flexible Architecture** - Easy to extend with additional customization options
+- **Performance** - No performance impact when customization is not used
+
+### Developer Experience
+- **Easy Configuration** - Simple to disable template wrapping or provide custom wrapper
+- **Context Support** - Components can access config without prop drilling
+- **Comprehensive Types** - Well-documented interfaces with examples
+
 ## [0.19.0] - 2025-07-30
 
 ### Added

package/PREVIEW_CUSTOMIZATION_TASK.md

@@ -0,0 +1,201 @@
+# Email Preview Customization Task
+
+## Overview
+The email preview in the plugin currently wraps all content in a default email template, which conflicts with custom email templates that users might implement. We need to make the preview customizable so users can control how their emails are rendered in the preview.
+
+## Problem
+- The plugin's `EmailPreview.tsx` always wraps content with `wrapInTemplate: true` (line 54)
+- This causes styling differences between the preview and what's actually sent to email providers
+- Users who implement custom email templates see inconsistent previews
+
+## Required Changes
+
+### 1. Update Type Definitions (`src/types/index.ts`)
+
+Add email preview customization options to the `BroadcastCustomizations` interface:
+
+```typescript
+export interface BroadcastCustomizations {
+  // ... existing fields ...
+  
+  /**
+   * Email preview customization options
+   */
+  emailPreview?: {
+    /**
+     * Whether to wrap preview content in default email template
+     * @default true
+     */
+    wrapInTemplate?: boolean
+    
+    /**
+     * Custom wrapper function for preview content
+     * Receives the converted HTML and should return wrapped HTML
+     */
+    customWrapper?: (content: string, options?: {
+      subject?: string
+      preheader?: string
+    }) => string | Promise<string>
+    
+    /**
+     * Custom preview component to replace the default one entirely
+     * If provided, this component will be used instead of the default EmailPreview
+     */
+    customPreviewComponent?: string // Path to custom component for import map
+  }
+}
+```
+
+### 2. Update Email Preview Component (`src/components/Broadcasts/EmailPreview.tsx`)
+
+Modify the component to use the customization options:
+
+1. Import the plugin config (you'll need to pass it through props or context)
+2. Update the `convertContent` function (around line 42) to respect customization options:
+
+```typescript
+// Around line 51-54, replace:
+const emailHtml = await convertToEmailSafeHtml(content, {
+  wrapInTemplate: true,
+  preheader,
+})
+
+// With:
+const emailHtml = await convertToEmailSafeHtml(content, {
+  wrapInTemplate: pluginConfig?.customizations?.broadcasts?.emailPreview?.wrapInTemplate ?? true,
+  preheader,
+  customWrapper: pluginConfig?.customizations?.broadcasts?.emailPreview?.customWrapper,
+})
+```
+
+### 3. Update Email Safe HTML Utility (`src/utils/emailSafeHtml.ts`)
+
+Modify the `convertToEmailSafeHtml` function to support custom wrapper:
+
+1. Add `customWrapper` to the options interface (around line 36):
+```typescript
+options?: {
+  wrapInTemplate?: boolean
+  preheader?: string
+  mediaUrl?: string
+  customBlockConverter?: (node: any, mediaUrl?: string) => Promise<string>
+  payload?: any
+  populateFields?: string[] | ((blockType: string) => string[])
+  customWrapper?: (content: string, options?: { preheader?: string }) => string | Promise<string>
+}
+```
+
+2. Update the wrapping logic (around line 54-57):
+```typescript
+// Optionally wrap in email template
+if (options?.wrapInTemplate) {
+  if (options.customWrapper) {
+    return await Promise.resolve(options.customWrapper(sanitizedHtml, { preheader: options.preheader }))
+  }
+  return wrapInEmailTemplate(sanitizedHtml, options.preheader)
+}
+```
+
+### 4. Update Email Preview Field (`src/components/Broadcasts/EmailPreviewField.tsx`)
+
+Pass the plugin config to the EmailPreview component. You'll need to:
+
+1. Import and use a context or prop to get the plugin config
+2. Pass it to the EmailPreview component (around line 158):
+
+```typescript
+<EmailPreview
+  content={fields.content?.value as SerializedEditorState || null}
+  subject={fields.subject?.value as string || 'Email Subject'}
+  preheader={fields.preheader?.value as string}
+  mode={previewMode}
+  onValidation={handleValidation}
+  pluginConfig={pluginConfig} // Add this
+/>
+```
+
+### 5. Create Plugin Config Context (`src/contexts/PluginConfigContext.tsx`) - NEW FILE
+
+Create a context to pass plugin config throughout the component tree:
+
+```typescript
+import React, { createContext, useContext } from 'react'
+import type { NewsletterPluginConfig } from '../types'
+
+const PluginConfigContext = createContext<NewsletterPluginConfig | null>(null)
+
+export const PluginConfigProvider: React.FC<{
+  config: NewsletterPluginConfig
+  children: React.ReactNode
+}> = ({ config, children }) => {
+  return (
+    <PluginConfigContext.Provider value={config}>
+      {children}
+    </PluginConfigContext.Provider>
+  )
+}
+
+export const usePluginConfig = () => {
+  const config = useContext(PluginConfigContext)
+  if (!config) {
+    throw new Error('usePluginConfig must be used within PluginConfigProvider')
+  }
+  return config
+}
+```
+
+### 6. Update Broadcasts Collection (`src/collections/Broadcasts.ts`)
+
+Wrap the admin UI components with the PluginConfigProvider. This is more complex and might require modifying how components are initialized.
+
+## Testing Instructions
+
+1. Create a test configuration that uses custom email preview:
+```typescript
+newsletterPlugin({
+  customizations: {
+    broadcasts: {
+      emailPreview: {
+        wrapInTemplate: false,
+        // Or with custom wrapper:
+        customWrapper: async (content, { preheader }) => {
+          return `<div class="my-custom-wrapper">${content}</div>`
+        }
+      }
+    }
+  }
+})
+```
+
+2. Verify that:
+   - Default behavior (with template) still works when no customization is provided
+   - Setting `wrapInTemplate: false` shows raw content without wrapper
+   - Custom wrapper function is called and applied correctly
+   - Preview matches what's sent to email providers
+
+## Backward Compatibility
+
+- Default behavior must remain unchanged (wrap in template)
+- All customization options should be optional
+- Existing installations should work without any configuration changes
+
+## Additional Considerations
+
+1. **Custom Preview Component**: The `customPreviewComponent` option would allow complete replacement of the preview component, but this is a more complex feature that could be added later.
+
+2. **Preview Context**: Consider passing additional context to the custom wrapper like:
+   - Current user
+   - Broadcast metadata
+   - Provider configuration
+
+3. **Documentation**: Update the plugin README with examples of how to use these new customization options.
+
+## Implementation Order
+
+1. Start with type definitions
+2. Update emailSafeHtml utility  
+3. Modify EmailPreview component
+4. Test with various configurations
+5. Add documentation
+
+This approach provides maximum flexibility while maintaining backward compatibility and clean architecture.

package/README.md

@@ -806,6 +806,22 @@ newsletterPlugin({
             description: 'Custom description'
           }
         })
+      },
+      // Email preview customization (v0.20.0+)
+      emailPreview: {
+        // Disable default email template wrapping
+        wrapInTemplate: false,
+        
+        // Or provide a custom wrapper function
+        customWrapper: async (content, { subject, preheader }) => {
+          return `
+            <div class="my-custom-template">
+              <h1>${subject}</h1>
+              ${preheader ? `<p class="preheader">${preheader}</p>` : ''}
+              <div class="content">${content}</div>
+            </div>
+          `
+        }
       }
     }
   }
@@ -814,6 +830,87 @@ newsletterPlugin({
 
 **Note**: Custom blocks are processed server-side to ensure email compatibility and prevent Next.js serialization errors.
 
+### Email Preview Customization (v0.20.0+)
+
+The plugin now supports full customization of email preview rendering. This is useful when you have custom email templates and want the preview to match what's actually sent.
+
+#### Disable Default Template Wrapping
+
+If you're using your own email template system, you can disable the default template wrapping:
+
+```typescript
+newsletterPlugin({
+  customizations: {
+    broadcasts: {
+      emailPreview: {
+        wrapInTemplate: false // Show raw HTML without email template
+      }
+    }
+  }
+})
+```
+
+#### Custom Email Wrapper
+
+Provide your own wrapper function to match your email service's template:
+
+```typescript
+newsletterPlugin({
+  customizations: {
+    broadcasts: {
+      emailPreview: {
+        customWrapper: async (content, { subject, preheader }) => {
+          // Return your custom email template
+          return `
+            <!DOCTYPE html>
+            <html>
+              <head>
+                <title>${subject}</title>
+                <!-- Your custom styles -->
+              </head>
+              <body>
+                <div class="preheader">${preheader}</div>
+                ${content}
+                <!-- Your footer -->
+              </body>
+            </html>
+          `
+        }
+      }
+    }
+  }
+})
+```
+
+#### Advanced: Using with React Email
+
+If you're using React Email for templates, you can integrate it with the preview:
+
+```typescript
+import { render } from '@react-email/render'
+import { MyEmailTemplate } from './emails/MyEmailTemplate'
+
+newsletterPlugin({
+  customizations: {
+    broadcasts: {
+      emailPreview: {
+        customWrapper: async (content, { subject, preheader }) => {
+          return await render(
+            <MyEmailTemplate 
+              subject={subject}
+              preheader={preheader}
+              content={content}
+            />
+          )
+        }
+      }
+    }
+  }
+})
+```
+
+This ensures your preview exactly matches what subscribers will see.
+
 For complete extensibility documentation, see the [Extension Points Guide](./docs/architecture/extension-points.md).
 
 ## Troubleshooting

package/dist/collections.cjs

@@ -976,6 +976,12 @@ async function convertToEmailSafeHtml(editorState, options) {
   const rawHtml = await lexicalToEmailHtml(editorState, options?.mediaUrl, options?.customBlockConverter);
   const sanitizedHtml = import_isomorphic_dompurify.default.sanitize(rawHtml, EMAIL_SAFE_CONFIG);
   if (options?.wrapInTemplate) {
+    if (options.customWrapper) {
+      return await Promise.resolve(options.customWrapper(sanitizedHtml, {
+        preheader: options.preheader,
+        subject: options.subject
+      }));
+    }
     return wrapInEmailTemplate(sanitizedHtml, options.preheader);
   }
   return sanitizedHtml;
@@ -1870,11 +1876,14 @@ var createBroadcastPreviewEndpoint = (config, _collectionSlug) => {
         const mediaUrl = req.payload.config.serverURL ? `${req.payload.config.serverURL}/api/media` : "/api/media";
         req.payload.logger?.info("Populating media fields for email preview...");
         const populatedContent = await populateMediaFields(content, req.payload, config);
+        const emailPreviewConfig = config.customizations?.broadcasts?.emailPreview;
         const htmlContent = await convertToEmailSafeHtml(populatedContent, {
-          wrapInTemplate: true,
+          wrapInTemplate: emailPreviewConfig?.wrapInTemplate ?? true,
           preheader,
+          subject,
           mediaUrl,
-          customBlockConverter: config.customizations?.broadcasts?.customBlockConverter
+          customBlockConverter: config.customizations?.broadcasts?.customBlockConverter,
+          customWrapper: emailPreviewConfig?.customWrapper
         });
         return Response.json({
           success: true,