mail-react: Add a rich-text block factory for Tip-Tap content

[VPS-Ricky]

createTipTapRichTextBlock renders the CMS Tip-Tap rich text block in mails. It uses the same components as createRichTextBlock, so existing styling for the draft-js block also works here. It is a separate factory because the two store styling differently.

export const { MjmlTipTapRichTextBlock } = createTipTapRichTextBlock({
    textBlockStyles: {
        title: { variant: "title" },
        header: { variant: "header" },
    },
    textBlocks: {
        "unordered-list": { variant: "list" },
    },
});

In the admin, the content editor writes paragraphs and lists, and can give each one a style, such as title or header. The application defines these styles in the CMS block's textBlockStyles. The two mail options follow that:

• textBlockStyles: the look of each entry in the rich text editor's style dropdown.
• textBlocks: the default look of a paragraph or list, when a content editor did not select a style. Leave it out to use the theme's default variant.

Mails render all text as div elements, so a heading in a mail is a style, not a heading tag.

Screenshot

The same content in the demo Welcome Email, authored once in the draft-js block and once in the Tip-Tap block:

---

Task: https://vivid-planet.atlassian.net/browse/PHSB2C-12548

[nsams]

shouldn't we use a mechanism similar to site?
https://github.com/vivid-planet/dextinity/blob/main/demo/site/src/common/blocks/TipTapRichTextBlock.tsx

[VPS-Ricky]

shouldn't we use a mechanism similar to site? https://github.com/vivid-planet/dextinity/blob/main/demo/site/src/common/blocks/TipTapRichTextBlock.tsx

It's the same mechanism as our existing draft-js block, createRichTextBlock.
So a factory, returning the Html and Mjml versions of the block (so the same configuration can be used in different contexts), which then render the text components that are optimized for mail-clients and render the variants from the configured theme.

Is that what you mean?

[VPS-Ricky]

@greptileai review

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Adds new rich-text block type for email content.

The PR appears safe to merge based on this review.

Summary

The PR adds a Tip-Tap rich-text mail factory alongside the Draft.js factory and wires it into the demo’s admin, API, and mail rendering paths.

• It reuses themed text and table-based list components, with configurable block styles, marks, and links.
• It adds rendering tests, examples, documentation, and a changeset.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  CMS[CMS Tip-Tap content] --> Factory[createTipTapRichTextBlock]
  Factory --> Renderer[Tip-Tap content renderer]
  Renderer --> Text[Themed text blocks]
  Renderer --> Lists[Table-based lists]
  Renderer --> Inline[Marks and resolved links]
  Text --> Mail[HTML or MJML email]
  Lists --> Mail
  Inline --> Mail

Loading

_{Reviews (3) · Last reviewed commit: "Demo: Offer the Tip-Tap rich text block ..."}

[nsams]

Is that what you mean?

• for the old (draftjs) block we has nothing in our library and used redraft (example)
• for the new TipTap block we created a renderTipTapRichText helper in Site: Refactor TipTap rich text rendering into reusable utility #5624

....that is for "normal" sites, for mail-react:

• you made a createRichTextBlock for the draftjs block

The question I'm asking is if we could have something similar to site's renderTipTapRichText for mail-react

[VPS-Ricky]

The question I'm asking is if we could have something similar to site's renderTipTapRichText for mail-react

So you're asking if we should create a render-function instead of (or in addition to) the component/block factory, correct?

The reason for the factory is that we can control precisely how the text elements are rendered, like the specific table-structure we need for lists, so it renders consistently across mail-clients.

Font styling, responsive styling, spacings, etc. can all be controlled through the theme, registerStyles() and the factory’s options.

IMO replacing the factory with a render function would make it too easy to override the html structure with one that does not work consistently across mail-clients, while preventing the library from shipping fixes for specific mail-clients, if we discover new issues.

About adding the render-function in addition to the factory: it seems like one additional thing we'd need to support that will rarely to never be used in practice. Where it is used, we have the issue again, that fixes will not reach those projects.

[VPS-Ricky]

@greptileai review

[VPS-Ricky]

@greptileai

[VPS-Obi]

We discussed adding a render function when we added the Draft.js-based implementation (see #5873 (comment)). @VPS-Ricky convinced me that a factory is better because we need to support both MJML- and HTML-based rich text blocks, which would require two render function, which could drift apart.

Internally, the factory does little more than calling the render functions with correctly configured arguments:

dextinity/packages/mail-react/src/blocks/richText/draftJs/createRichTextBlock.tsx

Lines 104 to 127 in fa3c71f

	export function createRichTextBlock<TLinkTypes extends Record<string, unknown> = Record<string, unknown>>(
	options: CreateRichTextBlockOptions<TLinkTypes> = {},
	): {
	// The description below is duplicated in MjmlRichTextBlock.stories.tsx because Storybook cannot read TSDoc from factory return type properties. Update both when the description changes.
	/** Renders CMS RichText block data (draft-js raw content) as one `MjmlText` per draft block. Must be placed within an `MjmlColumn`. */
	MjmlRichTextBlock: (props: RichTextBlockProps) => ReactNode;
	// The description below is duplicated in HtmlRichTextBlock.stories.tsx because Storybook cannot read TSDoc from factory return type properties. Update both when the description changes.
	/** Renders CMS RichText block data (draft-js raw content) as one `HtmlText` div per draft block, for raw-HTML contexts such as `MjmlRaw`. Inside `MjmlRaw` in an `MjmlColumn`, place `HtmlRichTextBlock` in a `<tr>` and `<td>` of its own. */
	HtmlRichTextBlock: (props: RichTextBlockProps) => ReactNode;
	} {
	const blockTypes = options.blockTypes ?? {};
	const linkTypes = mergeLinkTypes<TLinkTypes>(options.linkTypes);
	const inline = options.inline ?? {};
	function MjmlRichTextBlock({ data }: RichTextBlockProps): ReactNode {
	return renderRichTextContent({ draftContent: data.draftContent, blockTypes, linkTypes, inline, blockTextComponent: MjmlBlockText });
	}
	function HtmlRichTextBlock({ data }: RichTextBlockProps): ReactNode {
	return renderRichTextContent({ draftContent: data.draftContent, blockTypes, linkTypes, inline, blockTextComponent: HtmlBlockText });
	}
	return { MjmlRichTextBlock, HtmlRichTextBlock };
	}

IMO we can use the same approach for the TipTap-based implementation.

[VPS-Andreas]

Rebased onto main while Ricky is away. #6383 was merged in the meantime and moved the TipTap block's text block styles from the top-level textBlockStyles option into styles on each text block and list. The demo mail blocks added in this PR still used the old option, so 8331de8 moves their styles over. The only other conflict was the migration table in the TipTap docs.