ADR-003: Notion-like Email Builder

• Status: Accepted
• Date: 2025-01-10

Context

The original email builder used a traditional 3-panel layout: a block palette on the left, a canvas in the center, and a property panel on the right. This is the standard approach used by most email editors (Mailchimp, Beehiiv, etc.).

User feedback and internal testing revealed problems:

• Cognitive overhead — users constantly context-switched between the palette, canvas, and property panel. Editing a block required: (1) click the block on canvas, (2) look right to find settings, (3) make changes, (4) look back to canvas to see the result.
• Wasted space — the palette and property panel consumed screen width even when not in use, leaving a narrow canvas that didn't represent the actual email width.
• Drag-and-drop friction — dragging blocks from a palette into a specific position was imprecise, especially for reordering existing blocks.

Notion, Linear, and modern document editors solve this with inline editing: content is edited where it lives, and tools appear contextually.

Decision

Replace the 3-panel layout with a single-column document canvas (Notion-like editor). Blocks are edited inline. Settings appear in a floating popover anchored to the selected block. New blocks are inserted via a slash command menu or a horizontal toolbar.

Key components:

• DocumentCanvas.vue replaces CanvasArea.vue
• BlockSettingsPopover.vue replaces PropertyPanel.vue
• FloatingFormatBar.vue for text formatting
• BlockInsertToolbar.vue for quick block insertion
• Slash command menu (/) for keyboard-first block insertion

Consequences

Enables:

• WYSIWYG editing — what you see on canvas is what the email looks like
• Keyboard-first workflow — slash commands, arrow key navigation, Enter to add blocks
• Full-width canvas that matches email rendering width
• Simpler mental model — "click to edit, type to write"
• Mobile-friendly editing (no multi-panel layout to squeeze)

Trade-offs:

• More complex component architecture — floating popovers need anchor management (useBlockSettingsPopover.ts)
• Layout blocks (Columns, Container, Hero) use defineAsyncComponent to break circular imports
• Old 3-panel components are kept for backward compatibility but no longer used by EmailBuilder.vue
• Some power-user features (bulk property editing, block tree view) are harder to surface without a persistent side panel