1d755983ff
# Email editor for Compose campaigns
## Short version
Campaign bodies are currently plain rich text. This PR turns the
composer into an email editor: a centered email canvas with section,
column, button, divider, image and raw-HTML blocks, each editable
through a settings side panel, rendered to email-safe HTML per recipient
at send time. Modelled on Resend's Broadcast editor.
**Product**
- Email canvas with page/body styling (background, width, padding,
corner radius, border, text colour, alignment)
- Blocks: section, 2/3 columns, button, divider, raw HTML, images —
insertable from a floating left rail or the slash menu
- A **section is a container whose typography cascades to its
contents**, so one part of an email can have its own look
- Block settings panel focuses whatever you select and shows its
effective values
- Per-recipient variables (`{{firstName}}`, `{{lastName}}`,
`{{fullName}}`, `{{email}}`, `{{personId}}`) usable in text,
button/link/image URLs, image labels and raw HTML
- Image upload by drag-drop, paste or file picker
**Technical**
- Presets now declare **capabilities** instead of surfaces forking the
editor; the UI derives itself from loaded extensions
- Editor behavior lives in `twenty-front`; the versioned email-document
schema and structural traversal live in `twenty-shared`; rendering lives
in `twenty-emails` — HTML is produced server-side per recipient
- Section typography cascade is **resolved at render time**, not left to
CSS: react-email hardcodes `fontSize`/`lineHeight` on every paragraph
and Outlook ignores `inherit`
- Logic vendored from Resend (MIT); all controls rebuilt on `twenty-ui`
+ Linaria
**Also fixes:** the unsubscribe footer was being appended *after*
`</html>`, outside the document, where Gmail strips it — legally
significant since unsubscribe is required.
---
## Detailed version
### Product requirements
**Problem.** The Compose campaign body was a single rich-text field.
Marketing email needs layout — banded sections, columns, call-to-action
buttons, images with links — and it needs that layout to survive
Outlook, which means table-based HTML rather than the divs a text editor
produces. It also needs per-recipient personalisation.
**Reference.** Resend's Broadcast editor, chosen because it solves the
same problem (TipTap authoring → react-email output) and is MIT
licensed.
#### What a user can now do
| Area | Capability |
|---|---|
| Canvas | Email renders as a centered page with its own background,
width, padding, corner radius and border |
| Blocks | Section, 2/3 columns, button, divider, raw HTML, image |
| Insertion | Floating left rail (pointer-first) or the `/` slash menu
(keyboard-first) |
| Sections | Own text colour, font size, line height, letter spacing and
alignment, cascading to everything inside |
| Images | Upload by drag-drop, paste or picker; link URL, alt text,
width, spacing, border |
| Raw HTML | Edited as source in the panel, previewed on the canvas with
scripts neutralised |
| Variables | `{{firstName}}`, `{{lastName}}`, `{{fullName}}`,
`{{email}}`, `{{personId}}` in text, button URLs, link hrefs and raw
HTML |
| Settings panel | Follows selection; shows effective values; opens
automatically when a block is clicked |
#### Deliberate product decisions
- **Variables display as literal placeholders**, not prose labels, so
the syntax is copyable into HTML blocks and button URLs by hand.
- **Sections inherit until they override.** The panel shows what
actually renders rather than blank fields, but writes nothing until you
edit — so changing the body text colour still flows into sections.
- **Headings keep their own scale** inside a styled section; only
colour, family and spacing cascade, otherwise every heading would
collapse to body size.
- **Clicking a block opens its settings**, but only on whole-node
selections, so typing inside a section does not reopen a panel you just
closed.
### Technical strategy
#### 1. Capability presets (the foundation)
Per-surface variation previously worked by **forking**: three separate
`useEditor` call sites with hardcoded extension arrays. Inside the
shared tree there was no variation at all — all five surfaces received a
byte-identical extension list, and presets controlled only sizing,
chrome and serialization format. Adding email blocks that way meant
either leaking section/column nodes into the record rich-text field and
workflow email body, or writing a fourth fork.
Now:
- a preset declares a **capability list** (`basicMarks`, `headings`,
`lists`, `links`, `images`, `campaignVariables`, `slashCommand`,
`blocks`, `mentions`)
- capabilities resolve to extensions through a factory registry
- the UI derives itself from the loaded extensions via
`hasEditorExtension` — no capability list is prop-drilled into a menu,
because the `Editor` already knows what it can do
The acceptance test was collapsing the AI chat fork into an `aiChat`
preset with no visible change to that composer. `campaignBody` is the
only preset opting into the shared `EMAIL_DOCUMENT_CAPABILITIES` today.
Workflow email keeps its current field UI, but can opt into the same
canvas, block settings and image uploader later without adding another
schema or renderer.
#### 2. Schema / renderer split
The hard constraint: **our HTML is produced server-side, per recipient,
at send time**, because variables substitute into nodes rather than into
a serialized string. That rules out Resend's
`renderToReactEmail`-on-the-extension pattern.
```
twenty-front TipTap extensions + node views + shared email settings UI
twenty-shared versioned email-document schema + structural traversal
twenty-emails react-email renderers (imported by twenty-server)
twenty-server surface-specific variable resolution, validation, send
```
Logic was **vendored, not depended on** — Resend's TipTap is 3.17
against our 3.4, and their UI is Radix. We copied the schema/serializer
approach and rebuilt every control on `twenty-ui` + Linaria.
#### 3. Section typography cascade
The subtle part, and the one that would have silently shipped broken.
Section typography *looks* like it should cascade via CSS. It does not:
```js
// react-email's Text
style: { fontSize: "14px", lineHeight: "24px", ...style, ...margins }
```
Every paragraph re-declares `fontSize` and `lineHeight`, overriding any
enclosing section. `inherit` is not a fix either — Outlook's Word engine
ignores it.
So the cascade is **resolved in the renderer**: the tree walk threads
the enclosing section's typography down and writes computed values
explicitly onto each text node. Nested sections refine what they
inherit.
Verified against real rendered output:
| | rendered |
|---|---|
| paragraph inside section | `font-size:22px; color:rgb(255,0,0);
letter-spacing:2px` |
| h1 inside section | `font-size:32px` (own scale) + section colour and
spacing |
| paragraph outside | `font-size:14px`, no colour — untouched |
#### 4. Storage
`bodyTemplate` stays serialized TipTap JSON in a `TEXT` column. Block
attributes are ProseMirror node attrs, so richer blocks add keys to JSON
already being serialized — no migration, and it flows into the existing
500 ms debounced draft save unchanged.
Since the feature has not shipped, the legacy HTML-string body path was
removed rather than maintained. That is a tightening, not just a
deletion: `bodyTemplate` is writable through the record API, and the old
fallback would interpolate an arbitrary string and email it as markup. A
body that is neither empty nor a valid TipTap document is now rejected
at the send gate.
#### 5. Image hosting
Inline assets use an `EmailImage` file folder with
`ignoreExpirationToken: true` and immutable cache headers, because
recipients' mail clients never authenticate and may open an email years
later. The shared uploader returns `{ fileId, url }`; the image node
keeps both the durable file identity and its delivery URL so
ownership/lifecycle or URL resolution can evolve later without a
document migration. The server verifies the uploaded bytes and only
accepts GIF, JPEG, PNG and WebP.
This is intentionally separate from workflow/email **attachments**.
Attachments remain private files that the server reads and embeds as
MIME parts at send time; inline images need a durable recipient-facing
URL. A future workflow canvas should reuse `useUploadEmailImage` for
inline content while keeping its existing attachment control unchanged.
Adding the folder requires three registrations — the folder config, the
route guard's `SUPPORTED_FILE_FOLDERS`, and `DIRECT_UPLOAD_FILE_FOLDERS`
in the upload service.
### Bugs fixed along the way
- **Unsubscribe footer was appended after `</html>`**, outside the
document, where Gmail strips it. Legally significant, since an
unsubscribe link is required. Now inserted before `</body>`.
- **Body text colour never reached the email.**
- **`onImageUpload` was declared but never passed** by any production
call site, so drag-drop and paste image upload were inert everywhere
outside Storybook.
- **Message lists were not user-facing**, so members could not be added
from the list page.
- **Image resize wrote an undeclared `width` attribute** that TipTap
silently dropped.
- **The text bubble menu appeared over selected atom blocks** with
nothing to format.
### Review notes / known limitations
**Security posture to check.** Anything in `EmailImage` is readable by
anyone holding the URL, forever. The server now enforces an image-only
MIME allowlist from sniffed bytes, but it cannot determine whether the
image itself is confidential. This remains a deliberate trade-off for
recipient-visible inline assets.
**Test gap.** The section typography cascade has no regression test:
react-email's `render()` hangs under Jest (tried 60s), and
`twenty-emails` has no test target at all. Verified by rendering through
the built package instead. Adding a test target there is worthwhile
follow-up.
**Sending needs configuration.** `EMAILING_DOMAIN_DRIVER` defaults to
`LOG`, which fakes a messageId, reports any domain as verified, and only
logs — a campaign reaches "sent" with nothing delivered. Real sending
needs `AWS_SES`.
**Unrelated platform bug found.** The pinned "Create new record" command
throws on viewless objects like `messageListMember`, because
`recordIndexId` derives from the current view.
**Not done.** Panel chrome from the reference: breadcrumb (`Page style /
Section`), collapsible groups, per-side spacing grid, and a
variable-insert button inside link fields. All presentation over the
same data.
**Deferred.** Drag-to-reorder blocks.
`@tiptap/extension-drag-handle-react@3.4.2` matches our pinned versions
exactly, so no upgrade is needed, but its behaviour around atom node
views (HTML block, image) is unverified and belongs in its own change.
<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/23657?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Félix Malfait <felix.malfait@gmail.com>
Co-authored-by: Félix Malfait <felix@twenty.com>
202 lines
5.8 KiB
TypeScript
202 lines
5.8 KiB
TypeScript
import { styled } from '@linaria/react';
|
|
import { type NodeViewProps, NodeViewWrapper } from '@tiptap/react';
|
|
import React, { useCallback, useRef, useState } from 'react';
|
|
import { isDefined } from 'twenty-shared/utils';
|
|
import { themeCssVariables } from 'twenty-ui/theme-constants';
|
|
|
|
const IMAGE_MIN_WIDTH = 32;
|
|
const IMAGE_MAX_WIDTH = 600;
|
|
|
|
const StyledNodeViewWrapperContainer = styled.div<{
|
|
align?: string;
|
|
}>`
|
|
display: flex;
|
|
height: 100%;
|
|
justify-content: ${({ align }) =>
|
|
align === 'center'
|
|
? 'center'
|
|
: align === 'right'
|
|
? 'flex-end'
|
|
: 'flex-start'};
|
|
`;
|
|
|
|
const StyledImageWrapper = styled.div<{ width?: number }>`
|
|
height: 100%;
|
|
`;
|
|
|
|
const StyledImageContainer = styled.div`
|
|
max-width: 100%;
|
|
position: relative;
|
|
`;
|
|
|
|
const StyledImage = styled.img`
|
|
height: auto;
|
|
max-width: 100%;
|
|
`;
|
|
|
|
const StyledImageHandle = styled.div<{ handle: 'left' | 'right' }>`
|
|
background-color: ${themeCssVariables.background.primaryInverted};
|
|
border: 1px solid ${themeCssVariables.background.primary};
|
|
border-radius: ${themeCssVariables.border.radius.md};
|
|
cursor: col-resize;
|
|
height: ${themeCssVariables.spacing[8]};
|
|
left: ${({ handle }) =>
|
|
handle === 'left' ? themeCssVariables.spacing[1] : 'auto'};
|
|
position: absolute;
|
|
right: ${({ handle }) =>
|
|
handle === 'right' ? themeCssVariables.spacing[1] : 'auto'};
|
|
top: 50%;
|
|
transform: translateY(-50%);
|
|
|
|
width: ${themeCssVariables.spacing[2]};
|
|
z-index: 1;
|
|
`;
|
|
|
|
type ResizeParams = {
|
|
initialWidth: number;
|
|
initialClientX: number;
|
|
handleUsed: 'left' | 'right';
|
|
};
|
|
|
|
type ResizableImageViewProps = NodeViewProps;
|
|
|
|
export const ResizableImageView = (props: ResizableImageViewProps) => {
|
|
const { editor, node, updateAttributes } = props;
|
|
const { width: initialWidth, align = 'left', src, alt } = node.attrs;
|
|
|
|
const imageWrapperRef = useRef<HTMLDivElement>(null);
|
|
|
|
// Controls visibility of resize handles when hovering over the image
|
|
const [isHovering, setIsHovering] = useState(false);
|
|
const [width, setWidth] = useState(initialWidth || 0);
|
|
// Controls actual resize operation state (null = not resizing, object = actively resizing)
|
|
const [resizeParams, setResizeParams] = useState<ResizeParams | null>(null);
|
|
|
|
// Create stable event handlers using a closure approach
|
|
const createMouseHandlers = useCallback(() => {
|
|
let currentResizeParams: ResizeParams | null = null;
|
|
|
|
const handleMouseMove = (event: MouseEvent) => {
|
|
const imageWrapper = imageWrapperRef.current;
|
|
|
|
if (!isDefined(currentResizeParams) || !isDefined(imageWrapper)) {
|
|
return;
|
|
}
|
|
|
|
const deltaX = event.clientX - currentResizeParams.initialClientX;
|
|
const { initialWidth, handleUsed } = currentResizeParams;
|
|
|
|
let newWidth =
|
|
align === 'center'
|
|
? initialWidth + (handleUsed === 'left' ? -deltaX * 2 : deltaX * 2)
|
|
: initialWidth + (handleUsed === 'left' ? -deltaX : deltaX);
|
|
|
|
const maxWidth =
|
|
editor.view.dom.firstElementChild?.clientWidth || IMAGE_MAX_WIDTH;
|
|
newWidth = Math.min(Math.max(newWidth, IMAGE_MIN_WIDTH), maxWidth);
|
|
|
|
setWidth(newWidth);
|
|
imageWrapper.style.width = `${newWidth}px`;
|
|
};
|
|
|
|
const handleMouseUp = (event: MouseEvent) => {
|
|
const imageWrapper = imageWrapperRef.current;
|
|
|
|
if (!isDefined(imageWrapper) || !isDefined(currentResizeParams)) {
|
|
return;
|
|
}
|
|
|
|
if (
|
|
(!event.target || !imageWrapper.contains(event.target as Node)) &&
|
|
isHovering
|
|
) {
|
|
setIsHovering(false);
|
|
return;
|
|
}
|
|
|
|
const finalWidth = imageWrapper.clientWidth;
|
|
currentResizeParams = null;
|
|
setResizeParams(null);
|
|
updateAttributes({ width: finalWidth });
|
|
|
|
window.removeEventListener('mousemove', handleMouseMove);
|
|
window.removeEventListener('mouseup', handleMouseUp);
|
|
};
|
|
|
|
const startResize = (resizeParams: ResizeParams) => {
|
|
currentResizeParams = resizeParams;
|
|
setResizeParams(resizeParams);
|
|
|
|
window.addEventListener('mousemove', handleMouseMove);
|
|
window.addEventListener('mouseup', handleMouseUp);
|
|
};
|
|
|
|
return { startResize };
|
|
}, [editor, align, isHovering, updateAttributes]);
|
|
|
|
const { startResize } = createMouseHandlers();
|
|
|
|
const handleImageHandleMouseDown = useCallback(
|
|
(handle: 'left' | 'right', event: React.MouseEvent<HTMLDivElement>) => {
|
|
event.preventDefault();
|
|
|
|
const resizeParams = {
|
|
initialWidth: imageWrapperRef.current?.clientWidth ?? IMAGE_MAX_WIDTH,
|
|
initialClientX: event.clientX,
|
|
handleUsed: handle,
|
|
};
|
|
|
|
startResize(resizeParams);
|
|
},
|
|
[startResize],
|
|
);
|
|
|
|
const handleImageHover = useCallback(() => {
|
|
if (!editor.isEditable) {
|
|
return;
|
|
}
|
|
|
|
setIsHovering(true);
|
|
}, [editor.isEditable]);
|
|
|
|
const handleImageHoverEnd = useCallback(() => {
|
|
setIsHovering(false);
|
|
}, []);
|
|
|
|
return (
|
|
<NodeViewWrapper>
|
|
<StyledNodeViewWrapperContainer
|
|
onMouseEnter={handleImageHover}
|
|
onMouseLeave={handleImageHoverEnd}
|
|
align={align}
|
|
>
|
|
<StyledImageWrapper
|
|
ref={imageWrapperRef}
|
|
style={{ width: width ? `${width}px` : 'fit-content' }}
|
|
>
|
|
<StyledImageContainer>
|
|
<StyledImage
|
|
src={src}
|
|
alt={alt}
|
|
draggable={false}
|
|
contentEditable={false}
|
|
/>
|
|
{(isHovering || isDefined(resizeParams)) && (
|
|
<>
|
|
<StyledImageHandle
|
|
handle="left"
|
|
onMouseDown={(e) => handleImageHandleMouseDown('left', e)}
|
|
/>
|
|
<StyledImageHandle
|
|
handle="right"
|
|
onMouseDown={(e) => handleImageHandleMouseDown('right', e)}
|
|
/>
|
|
</>
|
|
)}
|
|
</StyledImageContainer>
|
|
</StyledImageWrapper>
|
|
</StyledNodeViewWrapperContainer>
|
|
</NodeViewWrapper>
|
|
);
|
|
};
|