EmailTemplateEditor

Install

import { EmailTemplateEditor, EmailPreview, EmailTemplate, EmailMode, EmailBlock, EmailBlockType, PreviewViewport, VariableSchema, renderEmailToHtml, interpolateVariables, extractVariables } from "@8maverik8/design";

Examples

import {
  EmailTemplateEditor,
  type EmailTemplate,
  type VariableSchema,
} from "@8maverik8/design";

const schema: VariableSchema = {
  variables: [
    { path: "user.first_name", label: "First name",     sample: "Oleg" },
    { path: "user.email",      label: "Email",          sample: "oleg@oapps.io" },
    { path: "org.name",        label: "Organization",   sample: "OAPPS" },
    { path: "invite.url",      label: "Invite link",    sample: "https://app.oapps.io/i/…" },
    { path: "app.unsubscribe_url", label: "Unsubscribe", sample: "https://app.oapps.io/u/…" },
  ],
};

const initial: EmailTemplate = {
  id: "tpl_invite",
  name: "Team invitation",
  subject: "You're invited to {{org.name}}",
  preheader: "Set up your account in 7 days",
  fromName: "OAPPS",
  replyTo: "support@oapps.io",
  mode: "branded",
  body: {
    mode: "branded",
    width: 600,
    blocks: [
      // … shape laid out per the EmailBlock variants table.
    ],
  },
};

const [value, setValue] = useState<EmailTemplate>(initial);

<EmailTemplateEditor
  schema={schema}
  value={value}
  onChange={setValue}
  // Optional — when provided, an "Open ↗" button appears in the
  // chrome bar in Preview mode, pointing at the consumer-owned
  // standalone preview route. The route should render <EmailPreview>.
  previewUrl={`/_preview/${value.id}`}
/>

// Standalone preview route (e.g. app/_preview/[id]/page.tsx in Cip):
// <EmailPreview value={template} viewport="desktop" schema={schema} />

// Persist value as JSON on save.
// On send: const html = renderEmailToHtml(value, { user, org, invite, app });

const initial: EmailTemplate = {
  id: "tpl_trial_day_7",
  name: "Trial — day 7 nudge",
  subject: "Quick note about your {{org.name}} trial",
  preheader: undefined,
  fromName: "Oleg from OAPPS",
  replyTo: "oleg@oapps.io",
  mode: "plain",
  signature: "auto",
  body: {
    mode: "plain",
    doc: {
      // ProseMirror JSON — paragraphs with bold / italic / link / variable marks.
    },
  },
};

<EmailTemplateEditor schema={schema} value={value} onChange={setValue} />

Variants

Anatomy

• valueControlled JSON document — `EmailTemplate`. Persist as-is, hydrate on mount. Subject, preheader, fromName, replyTo, mode, signature, and a `body` discriminated by mode.
• schema`VariableSchema` — list of variables the consumer's data model exposes. Same shape as `RuleSchema.fields`, reused. Each variable has `path` (dotted, e.g. `user.first_name`), `label`, optional `sample` value for previewing.
• onChangeFires on every edit with the next `EmailTemplate`. Caller decides debounce / autosave / explicit Save.
• VariablePaletteLeft rail — categorised list of variables and (in branded mode) the block palette. Click a variable to insert at cursor; click a block to append at end.
• EmailCanvasCenter column. In `branded`, renders the dot-grid background and centers a `<EmailFrame>` locked to 600px. In `plain`, no frame — centered `max-w-prose` over plain background.
• EmailInspectorRight rail. Contextual: when a block is selected → block-level props (image src, button href, alignment, padding). When nothing selected → template-level props (subject, preheader, fromName, replyTo, signature for plain mode).
• BubbleToolbarFloating formatting menu over selected text in any TipTap-backed block. Bold / Italic / Underline / Strikethrough / Link, plus pop-outs for text size (S 12px · M 14px · L 18px), font family (Sans / Serif / Mono — email-safe stacks), and text color (6 token-bound swatches). No arbitrary px or hex input — clients render fractional sizes and free palettes inconsistently.
• EmailPreviewRead-only preview component for the chrome bar's Preview mode AND for consumer-owned standalone preview routes (e.g. `/_preview/<id>` in Cip). Renders the actual email HTML inside a sandboxed iframe at one of three viewports — Desktop (800px), Tablet (600px), Mobile (380px) — wrapped in a stylised device-frame outline. Auto-fills sample variable values from `schema.variables[].sample` when `vars` is omitted. Pass `bare` to drop the device chrome.
• renderEmailToHtml(value, vars)Server-safe renderer. Branded → table-based HTML with inline styles for Outlook compatibility. Plain → minimal HTML + `text/plain` alternative. Supports `bold`, `italic`, `underline`, `strike`, `link`, and a unified `textStyle` mark carrying `color` / `fontFamily` / `fontSize`. Variables interpolated via the second arg.

Guidelines

• Define the variable schema close to your data model and pass it in. Like RuleBuilder, the editor is dumb about your variables — that's the point. One component, every product, every email type.
• Treat the emitted JSON as the contract you persist server-side. The same JSON is what your `POST /api/templates` accepts and what the renderer consumes when sending — no UI-to-API translation layer.
• Use `mode: 'plain'` for trial-day-7 / re-engagement / personal outreach where the message should feel hand-typed. Branded HTML in those slots fights the intent.
• Use `mode: 'branded'` for transactional (invite, password reset, receipt) and broadcast announcements where brand identity matters and you control rendering across clients.
• Render an HTML editor (TipTap full kit, Slate, ProseMirror raw) directly as your editing surface.HTML-as-source-of-truth makes variable insertion fragile, breaks when you need server-side rendering for transactional sends (no JSDOM), and ties your contract to a vendor's document model. JSON blocks + targeted TipTap-for-inline is the right split.
• Use the editor as a generic page-builder.Email is its own constraint set: 600px-ish width, table-based HTML, inline styles, conservative typography. Don't extend the block list with grids / columns / accordions — those don't render reliably in Outlook 2007+, Apple Mail, Gmail clipping, etc. If you need a marketing page, build a marketing page.
• Switch modes mid-edit by remounting with a different value shape.Mode is a top-level prop (`value.mode`); the editor handles the transition with deterministic content migration (branded→plain merges all text-blocks into one TipTap doc; plain→branded wraps the doc in one paragraph block). Don't rebuild value externally.
• Bypass the renderer when sending.`renderEmailToHtml(value, vars)` is the only supported way to produce the wire HTML. It does the table conversion, inline-styles, variable interpolation, link rewriting (UTM / unsubscribe / preheader-injection). Calling it from one place keeps preview === production.