Feat/advanced text editor capability presets (#23657)

# 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.  <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>  --------- Co-authored-by: Félix Malfait <felix.malfait@gmail.com> Co-authored-by: Félix Malfait <felix@twenty.com>
2026-08-05 12:38:06 +02:00
parent 5effee7754
commit 1d755983ff
243 changed files with 7620 additions and 569 deletions
@@ -329,7 +329,6 @@ export const RecordDetailRelationSectionDropdownToMany = ({
      createNewRecordAndOpenSidePanel,
      createTargetRecord,
      dropdownId,
-      fieldName,
      isMorphJunction,
      isJunctionRelation,
      junctionConfig,
@@ -4,6 +4,8 @@ import {
  type AdvancedTextEditorPresetName,
 } from '@/advanced-text-editor/constants/AdvancedTextEditorPresets';
 import { useAdvancedTextEditor } from '@/advanced-text-editor/hooks/useAdvancedTextEditor';
+import { type UploadedImage } from '@/advanced-text-editor/types/UploadedImage';
+import { serializeAdvancedTextEditorContent } from '@/advanced-text-editor/utils/serializeAdvancedTextEditorContent';
 import { FormFieldInputContainer } from '@/object-record/record-field/ui/form-types/components/FormFieldInputContainer';
 import { type VariablePickerComponent } from '@/object-record/record-field/ui/form-types/types/VariablePickerComponent';
 import { InputHint } from '@/ui/input/components/InputHint';
@@ -15,7 +17,8 @@ import { useRemoveFocusItemFromFocusStackById } from '@/ui/utilities/focus/hooks
 import { FocusComponentType } from '@/ui/utilities/focus/types/FocusComponentType';
 import { styled } from '@linaria/react';
 import { useLingui } from '@lingui/react/macro';
-import { useId, useState } from 'react';
+import { type Editor } from '@tiptap/core';
+import { useEffect, useId, useState } from 'react';
 import { isDefined } from 'twenty-shared/utils';
 import { IconMaximize } from 'twenty-ui/icon';
 import { LightIconButton } from 'twenty-ui/input';
@@ -97,13 +100,14 @@ type FormAdvancedTextFieldInputProps = {
  readonly?: boolean;
  placeholder?: string;
  VariablePicker?: VariablePickerComponent;
-  onImageUpload?: (file: File) => Promise<string>;
+  onImageUpload?: (file: File) => Promise<UploadedImage>;
  onImageUploadError?: (error: Error, file: File) => void;
  preset: AdvancedTextEditorPresetName;
  // Escape hatch for surfaces that share a preset but need their own height.
  minHeight?: number;
  enableFullScreen?: boolean;
  fullScreenBreadcrumbs?: BreadcrumbProps['links'];
+  onEditorReady?: (editor: Editor | null) => void;
 };

 export const FormAdvancedTextFieldInput = ({
@@ -121,6 +125,7 @@ export const FormAdvancedTextFieldInput = ({
  minHeight,
  enableFullScreen,
  fullScreenBreadcrumbs,
+  onEditorReady,
 }: FormAdvancedTextFieldInputProps) => {
  const {
    contentType,
@@ -143,17 +148,12 @@ export const FormAdvancedTextFieldInput = ({

  const editor = useAdvancedTextEditor(
    {
+      preset,
      placeholder: placeholder,
      readonly,
      defaultValue,
-      contentType,
      onUpdate: (editor) => {
-        if (contentType === 'markdown' || contentType === 'html') {
-          onChange?.(editor.getHTML());
-        } else {
-          const jsonContent = editor.getJSON();
-          onChange?.(JSON.stringify(jsonContent));
-        }
+        onChange?.(serializeAdvancedTextEditorContent({ editor, contentType }));
      },
      onFocus: () => {
        pushFocusItemToFocusStack({
@@ -172,11 +172,18 @@ export const FormAdvancedTextFieldInput = ({
      },
      onImageUpload,
      onImageUploadError,
-      enableSlashCommand: true,
    },
    [isFullScreen],
  );

+  useEffect(() => {
+    onEditorReady?.(editor);
+
+    return () => {
+      onEditorReady?.(null);
+    };
+  }, [editor, onEditorReady]);
+
  const handleEnterFullScreen = () => {
    setIsFullScreen(true);
  };
@@ -209,6 +216,10 @@ export const FormAdvancedTextFieldInput = ({
    hasClosePageButton: !isMobile,
  });

+  if (!isDefined(editor)) {
+    return null;
+  }
+
  const fullScreenOverlay = isFullScreenEnabled
    ? renderFullScreenModal(
        <div data-globally-prevent-click-outside="true">
@@ -217,6 +228,7 @@ export const FormAdvancedTextFieldInput = ({
              editor={editor}
              readonly={readonly}
              minHeight={editorMinHeight}
+              chrome={chrome}
            />
          </StyledFullScreenEditorContainer>
        </div>,
@@ -224,10 +236,6 @@ export const FormAdvancedTextFieldInput = ({
      )
    : null;

-  if (!isDefined(editor)) {
-    return null;
-  }
-
  return (
    <>
      <StyledAdvancedTextFieldContainerWrapper
@@ -245,6 +253,7 @@ export const FormAdvancedTextFieldInput = ({
                  editor={editor}
                  readonly={readonly}
                  minHeight={editorMinHeight}
+                  chrome={chrome}
                />
              )}

@@ -263,7 +263,6 @@ export const RelationOneToManyFieldInput = () => {
      createNewRecordAndOpenSidePanel,
      createTargetRecord,
      createJunctionRecord,
-      fieldName,
      instanceId,
      isMorphJunction,
      isJunctionRelation,