Merge pull request #6 from svycal/ap-521

Add conditional blocks (sc-if) with extensions system

Author: derrickreimer

.changeset/late-ends-repair.md

@@ -0,0 +1,5 @@
+---
+'@savvycal/mjml-editor': minor
+---
+
+Add conditional blocks extension

packages/mjml-editor/README.md

@@ -92,6 +92,7 @@ function App() {
 | `className` | `string` | Optional CSS class for the container |
 | `defaultTheme` | `'light' \| 'dark' \| 'system'` | Theme preference (default: `'system'`) |
 | `liquidSchema` | `LiquidSchema` | Optional schema for Liquid template autocomplete |
+| `extensions` | `EditorExtensions` | Optional extensions for custom features beyond standard MJML |
 | `applyThemeToDocument` | `boolean` | Whether to apply theme class to `document.documentElement`. Needed for dropdown/popover theming. Set to `false` if your app manages document-level theme classes. (default: `true`) |
 
 ## Liquid Template Support
@@ -129,6 +130,65 @@ function App() {
 
 When editing text content, typing `{{` will trigger variable autocomplete and `{%` will trigger tag autocomplete.
 
+## Extensions
+
+Extensions provide opt-in features beyond standard MJML. All extensions are disabled by default to maintain compatibility with stock MJML.
+
+```tsx
+import { MjmlEditor, type EditorExtensions } from '@savvycal/mjml-editor';
+
+function App() {
+  const [mjml, setMjml] = useState(initialMjml);
+
+  return (
+    <MjmlEditor
+      value={mjml}
+      onChange={setMjml}
+      extensions={{
+        conditionalBlocks: true,
+      }}
+    />
+  );
+}
+```
+
+### Available Extensions
+
+#### `conditionalBlocks`
+
+Enables the `sc-if` attribute for server-side conditional rendering using Liquid expressions.
+
+When enabled:
+- A "Condition (Liquid)" field appears in the Advanced section of the inspector for all block types
+- Blocks with conditions display an "if" badge indicator in both the canvas and outline tree
+- The Advanced section auto-expands when a block has a condition
+
+**How it works:**
+- The `sc-if` attribute is preserved in the MJML output for server-side processing
+- The attribute is stripped from preview rendering to avoid MJML validation warnings
+- Your server processes the Liquid condition and conditionally renders the block
+
+**Example MJML output:**
+
+```xml
+<mj-section sc-if="event.is_recurring">
+  <mj-column>
+    <mj-text>This section only appears for recurring events.</mj-text>
+  </mj-column>
+</mj-section>
+```
+
+**Server-side processing example (Ruby/Liquid):**
+
+```ruby
+# Before sending, wrap sc-if blocks with Liquid conditionals
+mjml = mjml.gsub(/<(mj-\w+)([^>]*)\ssc-if="([^"]+)"([^>]*)>/) do
+  tag, before, condition, after = $1, $2, $3, $4
+  "{% if #{condition} %}<#{tag}#{before}#{after}>"
+end
+# Don't forget to add closing {% endif %} tags as well
+```
+
 ## Exported Types
 
 The library exports TypeScript types for integration:
@@ -138,11 +198,20 @@ import type {
   MjmlNode,          // MJML document node structure
   MjmlTagName,       // Union of supported MJML tag names
   ContentBlockType,  // Union of content block types
+  EditorExtensions,  // Extensions configuration
   LiquidSchema,      // Schema for Liquid autocomplete
   LiquidSchemaItem,  // Individual variable/tag definition
 } from '@savvycal/mjml-editor';
 ```
 
+### EditorExtensions
+
+```typescript
+interface EditorExtensions {
+  conditionalBlocks?: boolean; // Enable sc-if attribute for conditional rendering
+}
+```
+
 ### LiquidSchema
 
 ```typescript

packages/mjml-editor/src/components/editor/BlockInspector.tsx

@@ -1,6 +1,7 @@
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
 import { ChevronRight, X, PanelRightClose } from 'lucide-react';
 import { useEditor } from '@/context/EditorContext';
+import { useExtensions } from '@/context/ExtensionsContext';
 import { ScrollArea } from '@/components/ui/scroll-area';
 import { Button } from '@/components/ui/button';
 import { Label } from '@/components/ui/label';
@@ -18,7 +19,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from '@/components/ui/select';
-import { getSchemaForTag } from '@/lib/mjml/schema';
+import { getSchemaForTag, filterSchemaByExtensions } from '@/lib/mjml/schema';
 import {
   parseClassNames,
   addClassToNode,
@@ -131,6 +132,7 @@ interface BlockInspectorProps {
 export function BlockInspector({ onTogglePanel }: BlockInspectorProps) {
   const { selectedBlock, updateAttributes, getInheritedValue, definedClasses } =
     useEditor();
+  const extensions = useExtensions();
 
   if (!selectedBlock) {
     return (
@@ -162,7 +164,10 @@ export function BlockInspector({ onTogglePanel }: BlockInspectorProps) {
     );
   }
 
-  const schema = getSchemaForTag(selectedBlock.tagName);
+  const schema = filterSchemaByExtensions(
+    getSchemaForTag(selectedBlock.tagName),
+    extensions
+  );
   const tagLabel =
     selectedBlock.tagName.replace('mj-', '').charAt(0).toUpperCase() +
     selectedBlock.tagName.replace('mj-', '').slice(1);
@@ -223,6 +228,12 @@ export function BlockInspector({ onTogglePanel }: BlockInspectorProps) {
                 groupedAttributes={groupedAttributes}
                 selectedBlock={selectedBlock}
                 handleAttributeChange={handleAttributeChange}
+                defaultOpenGroups={
+                  extensions.conditionalBlocks &&
+                  selectedBlock.attributes['sc-if']
+                    ? { advanced: true }
+                    : {}
+                }
               />
             ) : (
               <div className="space-y-5">
@@ -253,16 +264,25 @@ interface GroupedAttributeEditorProps {
   groupedAttributes: Record<string, { key: string; schema: AttributeSchema }[]>;
   selectedBlock: MjmlNode;
   handleAttributeChange: (key: string, value: string) => void;
+  defaultOpenGroups?: Record<string, boolean>;
 }
 
 function GroupedAttributeEditor({
   groupedAttributes,
   selectedBlock,
   handleAttributeChange,
+  defaultOpenGroups = {},
 }: GroupedAttributeEditorProps) {
-  const [openGroups, setOpenGroups] = useState<Record<string, boolean>>({});
+  const [openGroups, setOpenGroups] =
+    useState<Record<string, boolean>>(defaultOpenGroups);
   const { getInheritedValue } = useEditor();
 
+  // Reset open groups when selected block changes
+  useEffect(() => {
+    setOpenGroups(defaultOpenGroups);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- Reset only when block changes
+  }, [selectedBlock._id]);
+
   const toggleGroup = (group: string) => {
     setOpenGroups((prev) => ({ ...prev, [group]: !prev[group] }));
   };

packages/mjml-editor/src/components/editor/MjmlEditor.tsx

@@ -2,6 +2,7 @@ import { useEffect, useCallback, useState, useRef } from 'react';
 import { EditorProvider, useEditor } from '@/context/EditorContext';
 import { ThemeProvider, useTheme } from '@/context/ThemeContext';
 import { LiquidSchemaProvider } from '@/context/LiquidSchemaContext';
+import { ExtensionsProvider } from '@/context/ExtensionsContext';
 import { OutlineTree, GLOBAL_STYLES_ID } from './OutlineTree';
 import { EditorCanvas, type EditorTabType } from './EditorCanvas';
 import { BlockInspector } from './BlockInspector';
@@ -12,7 +13,7 @@ import {
   serializeMjml,
   createEmptyDocument,
 } from '@/lib/mjml/parser';
-import type { MjmlNode } from '@/types/mjml';
+import type { MjmlNode, EditorExtensions } from '@/types/mjml';
 import type { LiquidSchema } from '@/types/liquid';
 
 function parseInitialValue(value: string): MjmlNode {
@@ -33,6 +34,22 @@ interface MjmlEditorProps {
   className?: string;
   defaultTheme?: 'light' | 'dark' | 'system';
   liquidSchema?: LiquidSchema;
+  /**
+   * Enable optional editor extensions.
+   * Extensions provide opt-in features beyond standard MJML.
+   *
+   * Available extensions:
+   * - `conditionalBlocks`: Enable `sc-if` attribute for server-side conditional rendering
+   *
+   * @example
+   * ```tsx
+   * <MjmlEditor
+   *   extensions={{ conditionalBlocks: true }}
+   *   // ...
+   * />
+   * ```
+   */
+  extensions?: EditorExtensions;
   /**
    * Whether to apply the theme class to document.documentElement.
    * This is needed for Radix UI portals (popovers, menus, etc.) which
@@ -229,6 +246,7 @@ export function MjmlEditor({
   className,
   defaultTheme = 'system',
   liquidSchema,
+  extensions,
   applyThemeToDocument = true,
   showThemeToggle = true,
   defaultLeftPanelOpen = true,
@@ -263,18 +281,20 @@ export function MjmlEditor({
       defaultTheme={defaultTheme}
       applyToDocument={applyThemeToDocument}
     >
-      <LiquidSchemaProvider schema={liquidSchema}>
-        <ThemedEditorWrapper className={className}>
-          <EditorProvider initialDocument={initialDocument}>
-            <EditorContent
-              onChange={handleChange}
-              showThemeToggle={showThemeToggle}
-              defaultLeftPanelOpen={defaultLeftPanelOpen}
-              defaultRightPanelOpen={defaultRightPanelOpen}
-            />
-          </EditorProvider>
-        </ThemedEditorWrapper>
-      </LiquidSchemaProvider>
+      <ExtensionsProvider extensions={extensions}>
+        <LiquidSchemaProvider schema={liquidSchema}>
+          <ThemedEditorWrapper className={className}>
+            <EditorProvider initialDocument={initialDocument}>
+              <EditorContent
+                onChange={handleChange}
+                showThemeToggle={showThemeToggle}
+                defaultLeftPanelOpen={defaultLeftPanelOpen}
+                defaultRightPanelOpen={defaultRightPanelOpen}
+              />
+            </EditorProvider>
+          </ThemedEditorWrapper>
+        </LiquidSchemaProvider>
+      </ExtensionsProvider>
     </ThemeProvider>
   );
 }

packages/mjml-editor/src/components/editor/OutlineTree.tsx

@@ -22,6 +22,7 @@ import {
   PanelLeftClose,
 } from 'lucide-react';
 import { useEditor } from '@/context/EditorContext';
+import { useExtensions } from '@/context/ExtensionsContext';
 import { Button } from '@/components/ui/button';
 import {
   Popover,
@@ -94,13 +95,19 @@ function canAddColumns(tagName: string): boolean {
 // Custom node renderer for the tree
 function TreeNode({ node, style, dragHandle }: NodeRendererProps<MjmlNode>) {
   const { state, selectBlock, deleteBlock, addBlock, addColumn } = useEditor();
+  const extensions = useExtensions();
   const [isAddOpen, setIsAddOpen] = useState(false);
 
   const data = node.data;
   const isSelected = state.selectedBlockId === data._id;
   const hasChildren = node.children && node.children.length > 0;
   const showExpandButton = canHaveChildren(data.tagName);
 
+  // Only show condition indicator if extension is enabled
+  const condition = extensions.conditionalBlocks
+    ? data.attributes['sc-if']
+    : undefined;
+
   const handleSelect = (e: React.MouseEvent) => {
     e.stopPropagation();
     node.select();
@@ -174,6 +181,16 @@ function TreeNode({ node, style, dragHandle }: NodeRendererProps<MjmlNode>) {
         {getDisplayName(data.tagName)}
       </span>
 
+      {/* Conditional indicator */}
+      {condition && (
+        <span
+          className="text-[10px] px-1 py-0.5 bg-amber-500 text-white rounded font-mono mr-1"
+          title={`Condition: ${condition}`}
+        >
+          if
+        </span>
+      )}
+
       {/* Action buttons - visible on hover */}
       <div
         className={cn(

packages/mjml-editor/src/components/editor/visual-blocks/ConditionalIndicator.tsx

@@ -0,0 +1,16 @@
+interface ConditionalIndicatorProps {
+  condition?: string;
+}
+
+export function ConditionalIndicator({ condition }: ConditionalIndicatorProps) {
+  if (!condition) return null;
+
+  return (
+    <div
+      className="absolute top-1 right-1 z-10 bg-amber-500 text-white text-xs px-1.5 py-0.5 rounded font-mono"
+      title={`Condition: ${condition}`}
+    >
+      if
+    </div>
+  );
+}

packages/mjml-editor/src/components/editor/visual-blocks/VisualBlock.tsx

@@ -1,17 +1,19 @@
 import type { MjmlNode } from '@/types/mjml';
+import { useExtensions } from '@/context/ExtensionsContext';
 import { VisualText } from './VisualText';
 import { VisualImage } from './VisualImage';
 import { VisualButton } from './VisualButton';
 import { VisualDivider } from './VisualDivider';
 import { VisualSpacer } from './VisualSpacer';
 import { VisualSocial } from './VisualSocial';
 import { VisualRaw } from './VisualRaw';
+import { ConditionalIndicator } from './ConditionalIndicator';
 
 interface VisualBlockProps {
   node: MjmlNode;
 }
 
-export function VisualBlock({ node }: VisualBlockProps) {
+function renderBlock(node: MjmlNode) {
   switch (node.tagName) {
     case 'mj-text':
       return <VisualText node={node} />;
@@ -35,3 +37,17 @@ export function VisualBlock({ node }: VisualBlockProps) {
       );
   }
 }
+
+export function VisualBlock({ node }: VisualBlockProps) {
+  const extensions = useExtensions();
+  const condition = extensions.conditionalBlocks
+    ? node.attributes['sc-if']
+    : undefined;
+
+  return (
+    <div className="relative">
+      <ConditionalIndicator condition={condition} />
+      {renderBlock(node)}
+    </div>
+  );
+}

packages/mjml-editor/src/components/editor/visual-blocks/VisualColumn.tsx

@@ -1,5 +1,7 @@
 import { useEditor } from '@/context/EditorContext';
+import { useExtensions } from '@/context/ExtensionsContext';
 import { VisualBlock } from './VisualBlock';
+import { ConditionalIndicator } from './ConditionalIndicator';
 import { cn } from '@/lib/utils';
 import type { MjmlNode } from '@/types/mjml';
 import { buildPadding } from './helpers';
@@ -12,9 +14,13 @@ interface VisualColumnProps {
 
 export function VisualColumn({ node, totalColumns }: VisualColumnProps) {
   const { state, selectBlock } = useEditor();
+  const extensions = useExtensions();
   const isSelected = state.selectedBlockId === node._id;
   const attrs = useResolvedAttributes(node);
 
+  // Only show condition indicator if extension is enabled
+  const condition = extensions.conditionalBlocks ? attrs['sc-if'] : undefined;
+
   const handleClick = (e: React.MouseEvent) => {
     e.stopPropagation();
     selectBlock(node._id!);
@@ -113,6 +119,7 @@ export function VisualColumn({ node, totalColumns }: VisualColumnProps) {
       style={columnStyle}
       onClick={handleClick}
     >
+      <ConditionalIndicator condition={condition} />
       {hasInnerStyling ? (
         <div style={innerStyle}>
           {contentBlocks.map((block) => (