payload-plugin-newsletter 0.15.0 → 0.15.1

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [0.15.1] - 2025-07-27
+
+### Fixed
+- **Email-Compatible Block Editor** - Resolved Next.js serialization errors with custom blocks
+  - Custom blocks are now processed server-side using Lexical's proven BlocksFeature pattern
+  - Prevents "Functions cannot be passed directly to Client Components" errors
+  - Maintains full email compatibility while enabling custom block functionality
+- **Block Validation System** - Added validation utilities for email compatibility
+  - `validateEmailBlocks()` warns about potentially incompatible block types
+  - `createEmailSafeBlocks()` processes blocks for email-safe configurations
+  - Automatic detection of complex field types that may not render in email clients
+
+### Improved
+- **Server-Side Block Processing** - Enhanced `createEmailLexicalEditor()` function
+  - Processes custom blocks into Lexical editor configuration before client serialization
+  - Clean separation between email-compatible and web-only content blocks
+  - Better performance through pre-configured editor instances
+- **Enhanced Documentation** - Updated extension points guide with new approach
+  - Examples showing both legacy and new server-side processing methods
+  - Block validation utilities documentation
+  - Email compatibility best practices
+
+### Technical
+- Added `createEmailLexicalEditor()` for server-side editor configuration
+- Enhanced `createEmailContentField()` to accept pre-configured editors
+- New utility exports: `validateEmailBlocks`, `createEmailSafeBlocks`
+- Improved TypeScript support for custom block configurations
+
 ## [0.15.0] - 2025-07-27
 
 ### Added

package/README.md

@@ -727,7 +727,7 @@ newsletterPlugin({
 
 ### Extending the Broadcasts Collection (v0.15.0+)
 
-You can extend the Broadcasts collection with additional fields and custom blocks:
+You can extend the Broadcasts collection with additional fields and custom email-compatible blocks:
 
 ```typescript
 import type { Block } from 'payload'
@@ -753,7 +753,7 @@ newsletterPlugin({
           admin: { position: 'sidebar' }
         }
       ],
-      customBlocks: [customBlock],
+      customBlocks: [customBlock], // Processed server-side for email compatibility
       fieldOverrides: {
         content: (defaultField) => ({
           ...defaultField,
@@ -768,6 +768,8 @@ newsletterPlugin({
 })
 ```
 
+**Note**: Custom blocks are processed server-side to ensure email compatibility and prevent Next.js serialization errors.
+
 For complete extensibility documentation, see the [Extension Points Guide](./docs/architecture/extension-points.md).
 
 ## Troubleshooting

package/dist/collections.cjs

@@ -542,6 +542,103 @@ init_types();
 
 // src/fields/emailContent.ts
 var import_richtext_lexical = require("@payloadcms/richtext-lexical");
+
+// src/utils/blockValidation.ts
+var EMAIL_INCOMPATIBLE_TYPES = [
+  "chart",
+  "dataTable",
+  "interactive",
+  "streamable",
+  "video",
+  "iframe",
+  "form",
+  "carousel",
+  "tabs",
+  "accordion",
+  "map"
+];
+var validateEmailBlocks = (blocks) => {
+  blocks.forEach((block) => {
+    if (EMAIL_INCOMPATIBLE_TYPES.includes(block.slug)) {
+      console.warn(`\u26A0\uFE0F  Block "${block.slug}" may not be email-compatible. Consider creating an email-specific version.`);
+    }
+    const hasComplexFields = block.fields?.some((field) => {
+      const complexTypes = ["code", "json", "richText", "blocks", "array"];
+      return complexTypes.includes(field.type);
+    });
+    if (hasComplexFields) {
+      console.warn(`\u26A0\uFE0F  Block "${block.slug}" contains complex field types that may not render consistently in email clients.`);
+    }
+  });
+};
+var createEmailSafeBlocks = (customBlocks = []) => {
+  validateEmailBlocks(customBlocks);
+  const baseBlocks = [
+    {
+      slug: "button",
+      fields: [
+        {
+          name: "text",
+          type: "text",
+          label: "Button Text",
+          required: true
+        },
+        {
+          name: "url",
+          type: "text",
+          label: "Button URL",
+          required: true,
+          admin: {
+            description: "Enter the full URL (including https://)"
+          }
+        },
+        {
+          name: "style",
+          type: "select",
+          label: "Button Style",
+          defaultValue: "primary",
+          options: [
+            { label: "Primary", value: "primary" },
+            { label: "Secondary", value: "secondary" },
+            { label: "Outline", value: "outline" }
+          ]
+        }
+      ],
+      interfaceName: "EmailButton",
+      labels: {
+        singular: "Button",
+        plural: "Buttons"
+      }
+    },
+    {
+      slug: "divider",
+      fields: [
+        {
+          name: "style",
+          type: "select",
+          label: "Divider Style",
+          defaultValue: "solid",
+          options: [
+            { label: "Solid", value: "solid" },
+            { label: "Dashed", value: "dashed" },
+            { label: "Dotted", value: "dotted" }
+          ]
+        }
+      ],
+      interfaceName: "EmailDivider",
+      labels: {
+        singular: "Divider",
+        plural: "Dividers"
+      }
+    }
+  ];
+  return [
+    ...baseBlocks,
+    ...customBlocks
+  ];
+};
+
+// src/fields/emailContent.ts
 var createEmailSafeFeatures = (additionalBlocks) => {
   const baseBlocks = [
     {
@@ -679,16 +776,89 @@ var createEmailSafeFeatures = (additionalBlocks) => {
     })
   ];
 };
+var createEmailLexicalEditor = (customBlocks = []) => {
+  const emailSafeBlocks = createEmailSafeBlocks(customBlocks);
+  return (0, import_richtext_lexical.lexicalEditor)({
+    features: [
+      // Toolbars
+      (0, import_richtext_lexical.FixedToolbarFeature)(),
+      (0, import_richtext_lexical.InlineToolbarFeature)(),
+      // Basic text formatting
+      (0, import_richtext_lexical.BoldFeature)(),
+      (0, import_richtext_lexical.ItalicFeature)(),
+      (0, import_richtext_lexical.UnderlineFeature)(),
+      (0, import_richtext_lexical.StrikethroughFeature)(),
+      // Links with enhanced configuration
+      (0, import_richtext_lexical.LinkFeature)({
+        fields: [
+          {
+            name: "url",
+            type: "text",
+            required: true,
+            admin: {
+              description: "Enter the full URL (including https://)"
+            }
+          },
+          {
+            name: "newTab",
+            type: "checkbox",
+            label: "Open in new tab",
+            defaultValue: false
+          }
+        ]
+      }),
+      // Lists
+      (0, import_richtext_lexical.OrderedListFeature)(),
+      (0, import_richtext_lexical.UnorderedListFeature)(),
+      // Headings - limited to h1, h2, h3 for email compatibility
+      (0, import_richtext_lexical.HeadingFeature)({
+        enabledHeadingSizes: ["h1", "h2", "h3"]
+      }),
+      // Basic paragraph and alignment
+      (0, import_richtext_lexical.ParagraphFeature)(),
+      (0, import_richtext_lexical.AlignFeature)(),
+      // Blockquotes
+      (0, import_richtext_lexical.BlockquoteFeature)(),
+      // Upload feature for images
+      (0, import_richtext_lexical.UploadFeature)({
+        collections: {
+          media: {
+            fields: [
+              {
+                name: "caption",
+                type: "text",
+                admin: {
+                  description: "Optional caption for the image"
+                }
+              },
+              {
+                name: "altText",
+                type: "text",
+                label: "Alt Text",
+                required: true,
+                admin: {
+                  description: "Alternative text for accessibility and when image cannot be displayed"
+                }
+              }
+            ]
+          }
+        }
+      }),
+      // Email-safe blocks (processed server-side)
+      (0, import_richtext_lexical.BlocksFeature)({
+        blocks: emailSafeBlocks
+      })
+    ]
+  });
+};
 var emailSafeFeatures = createEmailSafeFeatures();
 var createEmailContentField = (overrides) => {
-  const features = createEmailSafeFeatures(overrides?.additionalBlocks);
+  const editor = overrides?.editor || createEmailLexicalEditor(overrides?.additionalBlocks);
   return {
     name: "content",
     type: "richText",
     required: true,
-    editor: (0, import_richtext_lexical.lexicalEditor)({
-      features
-    }),
+    editor,
     admin: {
       description: "Email content with limited formatting for compatibility",
       ...overrides?.admin
@@ -1040,13 +1210,15 @@ var createBroadcastsCollection = (pluginConfig) => {
                 }
               },
               // Apply content field customization if provided
-              customizations?.fieldOverrides?.content ? customizations.fieldOverrides.content(createEmailContentField({
-                admin: { description: "Email content" },
-                additionalBlocks: customizations.customBlocks
-              })) : createEmailContentField({
-                admin: { description: "Email content" },
-                additionalBlocks: customizations?.customBlocks
-              })
+              // Process blocks server-side to avoid client serialization issues
+              (() => {
+                const emailEditor = createEmailLexicalEditor(customizations?.customBlocks);
+                const baseField = createEmailContentField({
+                  admin: { description: "Email content" },
+                  editor: emailEditor
+                });
+                return customizations?.fieldOverrides?.content ? customizations.fieldOverrides.content(baseField) : baseField;
+              })()
             ]
           },
           {