@marlinjai/email-editor-core 0.2.0 → 0.4.0

package/dist/MjmlBuilder-DsiOyhiL.d.ts

@@ -0,0 +1,667 @@
+interface GradientStop {
+    color: string;
+    position: number;
+}
+interface BackgroundGradient {
+    type: 'linear' | 'radial';
+    angle: number;
+    stops: GradientStop[];
+}
+/**
+ * Converts a BackgroundGradient to a CSS background-image value.
+ * Returns undefined when stops array is empty.
+ *
+ * Examples:
+ *   buildGradientCSS({ type: 'linear', angle: 90, stops: [{color:'#f00',position:0},{color:'#00f',position:100}] })
+ *   // => "linear-gradient(90deg, #f00 0%, #00f 100%)"
+ *
+ *   buildGradientCSS({ type: 'radial', angle: 0, stops: [{color:'#f00',position:0},{color:'#00f',position:100}] })
+ *   // => "radial-gradient(circle, #f00 0%, #00f 100%)"
+ */
+declare function buildGradientCSS(gradient: BackgroundGradient): string | undefined;
+
+/**
+ * Spacing configuration for padding/margin
+ */
+interface Spacing {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+}
+/**
+ * Custom font definition
+ */
+interface FontDefinition {
+    name: string;
+    href: string;
+}
+/**
+ * Theme color for reusable brand colors
+ */
+interface ThemeColor {
+    name: string;
+    value: string;
+}
+/**
+ * MJML attributes the editor has no control for, kept as found (values as they
+ * stood in the source, XML entities included) and emitted again by the
+ * compiler after the attributes the editor sets. Written by the MJML import,
+ * so an imported document compiles the way its source did: a `css-class` the
+ * author's `mj-style` rules target, an `mj-class`, a button's `font-weight`.
+ */
+type ExtraAttributes = Record<string, string>;
+/**
+ * What an imported document's `<mj-head>` and `<mj-body>` carried beyond the
+ * fields the editor has (title, preview, fonts, breakpoint, styles). When
+ * present, the compiler emits `attributes` instead of its own default
+ * `<mj-attributes>` (so the source's `mj-all`, per-component defaults and
+ * `mj-class` definitions apply as they did), `bodyAttributes` on `<mj-body>`,
+ * and `headRaw` (for example `mj-html-attributes`) verbatim inside `<mj-head>`.
+ */
+interface MjmlHead {
+    /** The inner markup of `<mj-attributes>`, verbatim. An empty string means "no defaults at all". */
+    attributes?: string;
+    /** Attributes of `<mj-body>`, e.g. `background-color`, `width`. */
+    bodyAttributes?: ExtraAttributes;
+    /** Other head elements, verbatim, in source order. */
+    headRaw?: string;
+}
+/**
+ * Email template metadata
+ */
+interface TemplateMetadata {
+    subject?: string;
+    previewText?: string;
+    title?: string;
+    /** Epoch milliseconds (what the editor emits) or an ISO 8601 string */
+    createdAt?: string | number;
+    /** Epoch milliseconds (what the editor emits) or an ISO 8601 string */
+    updatedAt?: string | number;
+    fonts?: FontDefinition[];
+    themeColors?: ThemeColor[];
+    breakpoint?: string;
+    customCSS?: string;
+    inlineCSS?: string;
+    /** Set by the MJML import; see {@link MjmlHead}. */
+    mjmlHead?: MjmlHead;
+}
+/**
+ * Base block interface - all blocks extend this
+ */
+interface BaseBlock {
+    id: string;
+    type: string;
+    hidden?: boolean;
+    /** See {@link ExtraAttributes}. */
+    extraAttributes?: ExtraAttributes;
+}
+/**
+ * Text block with rich content
+ */
+interface TextBlock extends BaseBlock {
+    type: 'text';
+    content: string;
+    align?: 'left' | 'center' | 'right' | 'justify';
+    color?: string;
+    fontSize?: string;
+    fontFamily?: string;
+    padding?: Spacing;
+    lineHeight?: string;
+}
+/**
+ * Image block
+ */
+interface ImageBlock extends BaseBlock {
+    type: 'image';
+    src: string;
+    alt?: string;
+    width?: string;
+    height?: string;
+    align?: 'left' | 'center' | 'right';
+    href?: string;
+    padding?: Spacing;
+    borderRadius?: string;
+}
+/**
+ * Button block
+ */
+interface ButtonBlock extends BaseBlock {
+    type: 'button';
+    label: string;
+    href: string;
+    align?: 'left' | 'center' | 'right';
+    backgroundColor?: string;
+    color?: string;
+    borderRadius?: string;
+    border?: string;
+    padding?: Spacing;
+    innerPadding?: string;
+}
+/**
+ * Divider block
+ */
+interface DividerBlock extends BaseBlock {
+    type: 'divider';
+    borderColor?: string;
+    borderWidth?: string;
+    borderStyle?: 'solid' | 'dashed' | 'dotted';
+    width?: string;
+    padding?: Spacing;
+}
+/**
+ * Spacer block for vertical spacing
+ */
+interface SpacerBlock extends BaseBlock {
+    type: 'spacer';
+    height: string;
+}
+/**
+ * Custom branded header block (locked)
+ */
+interface HeaderBlock extends BaseBlock {
+    type: 'header';
+    locked: true;
+}
+/**
+ * Custom branded footer block (locked)
+ */
+interface FooterBlock extends BaseBlock {
+    type: 'footer';
+    locked: true;
+}
+/**
+ * Social link definition
+ */
+interface SocialLink {
+    platform: string;
+    url: string;
+    color?: string;
+}
+/**
+ * Social block for social media icons
+ */
+interface SocialBlock extends BaseBlock {
+    type: 'social';
+    links: SocialLink[];
+    iconSize?: string;
+    iconPadding?: string;
+    borderRadius?: string;
+    align?: 'left' | 'center' | 'right';
+    mode?: 'horizontal' | 'vertical';
+}
+/**
+ * Hero block with background image
+ */
+interface HeroBlock extends BaseBlock {
+    type: 'hero';
+    backgroundImage: string;
+    backgroundHeight?: string;
+    backgroundWidth?: string;
+    backgroundColor?: string;
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+    mode?: 'fixed-height' | 'fluid-height';
+}
+/**
+ * Accordion item
+ */
+interface AccordionItem {
+    title: string;
+    content: string;
+}
+/**
+ * Accordion block for collapsible content
+ */
+interface AccordionBlock extends BaseBlock {
+    type: 'accordion';
+    items: AccordionItem[];
+    iconPosition?: 'left' | 'right';
+    borderColor?: string;
+    fontFamily?: string;
+}
+/**
+ * Raw HTML block
+ */
+interface RawBlock extends BaseBlock {
+    type: 'raw';
+    html: string;
+}
+/**
+ * Navbar link definition
+ */
+interface NavbarLink {
+    href: string;
+    label: string;
+    color?: string;
+}
+/**
+ * Navbar block for navigation
+ */
+interface NavbarBlock extends BaseBlock {
+    type: 'navbar';
+    links: NavbarLink[];
+    hamburger?: boolean;
+    baseUrl?: string;
+    align?: 'left' | 'center' | 'right';
+    icoColor?: string;
+    padding?: Spacing;
+}
+/**
+ * Carousel image definition
+ */
+interface CarouselImage {
+    src: string;
+    alt?: string;
+    href?: string;
+    thumbnailSrc?: string;
+}
+/**
+ * Carousel block for image slideshows
+ */
+interface CarouselBlock extends BaseBlock {
+    type: 'carousel';
+    images: CarouselImage[];
+    thumbnails?: 'visible' | 'hidden';
+    borderRadius?: string;
+    iconWidth?: string;
+    tbBorderRadius?: string;
+    padding?: Spacing;
+}
+/**
+ * Table block for tabular data
+ */
+interface TableBlock extends BaseBlock {
+    type: 'table';
+    headers: string[];
+    rows: string[][];
+    align?: 'left' | 'center' | 'right';
+    color?: string;
+    fontFamily?: string;
+    fontSize?: string;
+    cellpadding?: string;
+    cellspacing?: string;
+    border?: string;
+    padding?: Spacing;
+}
+/**
+ * Union type of all possible blocks
+ */
+type Block = TextBlock | ImageBlock | ButtonBlock | DividerBlock | SpacerBlock | HeaderBlock | FooterBlock | SocialBlock | HeroBlock | AccordionBlock | RawBlock | NavbarBlock | CarouselBlock | TableBlock;
+/**
+ * Column within a section
+ */
+interface Column {
+    id: string;
+    width?: number;
+    blocks: Block[];
+    hidden?: boolean;
+    backgroundColor?: string;
+    backgroundGradient?: BackgroundGradient;
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+    padding?: Spacing;
+    /**
+     * Optional sub-columns. When non-empty, `blocks` MUST be empty
+     * (a column is either a leaf with blocks, or a group with sub-columns).
+     * See `docs/superpowers/specs/2026-04-26-nested-columns-design.md`.
+     */
+    subColumns?: SubColumn[];
+    /** See {@link ExtraAttributes}. */
+    extraAttributes?: ExtraAttributes;
+}
+/**
+ * Sub-column inside a "group"-kind Column. Holds only leaf blocks
+ * (text, image, button, divider, spacer, social). Cannot itself contain
+ * sub-columns (no nesting beyond depth 2).
+ */
+interface SubColumn {
+    id: string;
+    width: number;
+    blocks: Block[];
+    backgroundColor?: string;
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+    paddingTop?: string;
+    paddingRight?: string;
+    paddingBottom?: string;
+    paddingLeft?: string;
+}
+/**
+ * Section containing columns
+ */
+interface Section {
+    id: string;
+    type: 'section';
+    backgroundColor?: string;
+    backgroundImage?: string;
+    backgroundGradient?: BackgroundGradient;
+    backgroundPosition?: string;
+    backgroundRepeat?: 'repeat' | 'no-repeat';
+    backgroundSize?: string;
+    /**
+     * Full width (`full-width` in MJML). Inside a full-width {@link Wrapper},
+     * MJML renders the section at standard width whatever this says.
+     */
+    fullWidth?: boolean;
+    noStack?: boolean;
+    hidden?: boolean;
+    padding?: Spacing;
+    columns: Column[];
+    /**
+     * Emit the section's raw blocks straight into the parent (`<mj-body>`, or
+     * the `<mj-wrapper>` the section sits in) instead of inside an
+     * `<mj-section>`: markup that sat there in an imported document. Ignored as
+     * soon as the section holds any block that is not raw.
+     */
+    bodyRaw?: boolean;
+    /** See {@link ExtraAttributes}. */
+    extraAttributes?: ExtraAttributes;
+}
+/**
+ * A container around several sections (`<mj-wrapper>`): one background,
+ * border, radius and padding shared by the sections inside, with an optional
+ * vertical `gap` between them. Sits at the top level of a document, next to
+ * sections; it never holds another wrapper and never sits inside a section.
+ * It may be empty (it keeps its styling, and sections can be moved back in).
+ * Added in schema version 1.1.
+ */
+interface Wrapper {
+    id: string;
+    type: 'wrapper';
+    hidden?: boolean;
+    backgroundColor?: string;
+    /** `background-url` in MJML. */
+    backgroundImage?: string;
+    backgroundGradient?: BackgroundGradient;
+    backgroundPosition?: string;
+    backgroundRepeat?: 'repeat' | 'no-repeat';
+    backgroundSize?: string;
+    /** CSS border shorthand for all four sides, e.g. `1px solid #dddddd`. */
+    border?: string;
+    borderTop?: string;
+    borderRight?: string;
+    borderBottom?: string;
+    borderLeft?: string;
+    borderRadius?: string;
+    /** MJML's default when unset is `20px 0`. */
+    padding?: Spacing;
+    /** Full width (`full-width`): the background spans the whole mail width; the sections inside stay at standard width. */
+    fullWidth?: boolean;
+    /** Class names for `css-class`, space separated, for the document's own `mj-style` rules. */
+    cssClass?: string;
+    /** Vertical space between the sections inside, in px (`gap`, MJML 4.15 and later). */
+    gap?: string;
+    textAlign?: 'left' | 'center' | 'right';
+    /** See {@link ExtraAttributes}. */
+    extraAttributes?: ExtraAttributes;
+    sections: Section[];
+}
+/** What the top level of a document holds, in order: sections and wrappers. */
+type TopLevelItem = Section | Wrapper;
+/** The document schema versions: 1.1 added {@link Wrapper}. */
+type TemplateVersion = '1.0' | '1.1';
+/**
+ * Complete email template structure
+ */
+interface EmailTemplate {
+    /**
+     * The document's id. Optional: a document without one is valid, and the
+     * editor store assigns one when it opens it (see `TemplateModel`).
+     * `migrateTemplate` never adds or changes it.
+     */
+    id?: string;
+    /**
+     * The schema version. `migrateTemplate` brings every document it accepts to
+     * the current one (1.1); a 1.0 document cannot hold a wrapper.
+     */
+    version: TemplateVersion;
+    metadata: TemplateMetadata;
+    /** The document's top level, in order: sections and wrappers (see {@link TopLevelItem}). */
+    sections: TopLevelItem[];
+}
+/** Whether a top-level item is a {@link Wrapper}. */
+declare function isWrapper(item: TopLevelItem): item is Wrapper;
+/** Every section of a document in order, the ones inside wrappers included. */
+declare function allSections(items: readonly TopLevelItem[]): Section[];
+/**
+ * Result of MJML compilation
+ */
+interface CompileResult {
+    mjml: string;
+    html: string;
+    errors?: string[];
+}
+
+/** The `<mj-attributes>` a document gets unless it brings its own (`metadata.mjmlHead.attributes`). */
+declare const DEFAULT_MJML_ATTRIBUTES = "\n        <mj-all font-family=\"Georgia, serif\" />\n        <mj-text font-size=\"14px\" line-height=\"1.6\" />\n      ";
+/** Marks the editor's own raw markup so the MJML import can read the block back exactly. */
+declare const EDITOR_DATA_ATTRIBUTE: {
+    readonly social: "data-ee-social";
+    readonly subColumns: "data-ee-subcols";
+};
+/**
+ * Standard, padded base64 of a UTF-8 string, without Node's `Buffer`, so the
+ * builder runs in the browser too. Byte-identical to `Buffer.toString('base64')`.
+ */
+declare function base64Utf8(text: string): string;
+/**
+ * The comments that fence everything the editor's own compile adds to a
+ * document (`toMJML(template, { editor: true })`): ghosts for hidden nodes, a
+ * floor for empty columns, markers around a Raw block's verbatim markup. MJML
+ * keeps body comments in place, so the same fence survives into the HTML and
+ * {@link stripEditorMarkup} takes the additions out of either.
+ */
+declare const EDITOR_MARKER: {
+    readonly begin: "<!--ee:begin-->";
+    readonly end: "<!--ee:end-->";
+};
+/** The editor's additions removed from MJML or HTML, leaving the plain document. */
+declare function stripEditorMarkup(markup: string): string;
+/**
+ * The inline styles a Text block's content is wrapped in (`<div style>` inside
+ * MJML's own div), so nested tags inherit them. When this is empty the content
+ * sits directly in MJML's div. The canvas's in-place editor uses the same
+ * function to find the element that holds exactly `block.content`, so there
+ * is one rule for where the content lives.
+ */
+declare function textInlineStyles(block: Pick<TextBlock, 'align' | 'color' | 'fontSize' | 'fontFamily' | 'lineHeight'>): string[];
+/** Options of {@link MjmlBuilder.toMJML}. */
+interface BuildOptions {
+    /**
+     * Emit the editor's own affordances, fenced by {@link EDITOR_MARKER} so they
+     * strip back to the plain document: a ghost row for a hidden block, a ghost
+     * section or wrapper for a hidden one (never a ghost column: a column's
+     * width depends on its siblings' count, so a ghost would move the visible
+     * ones), a 48px floor in an empty column so it can be a drop target, and
+     * id markers around Raw blocks. Display only; never sent.
+     */
+    editor?: boolean;
+}
+/** A block's (or sub-columns') JSON, base64-encoded, for an {@link EDITOR_DATA_ATTRIBUTE}. */
+declare function encodeEditorData(value: unknown): string;
+/** `a + b` for two px lengths (`0` counts as px); undefined when either is something else. */
+declare function addPx(a: string, b: string): string | undefined;
+/**
+ * A section's padding with a wrapper's gap added on top. MJML's `mj-wrapper`
+ * has no gap of its own, so the editor's `gap` is compiled this way: every
+ * section after the first inside the wrapper gets the gap added to its top
+ * padding (MJML's default 20px when the section declares none). The MJML
+ * import takes it off again, so a document survives export and import.
+ * A top padding that is not a px length is left alone.
+ */
+declare function paddingWithGap(spacing: Spacing | undefined, gap: string): Spacing;
+/** Options for one {@link MJMLCompiler.compile} call. */
+interface CompileOptions {
+    /**
+     * MJML adds a Google Fonts `<link>` and `@import` on its own whenever a font
+     * family it knows (Open Sans, Droid Sans, Lato, Roboto, Ubuntu) appears in
+     * the document. `false` leaves them out, so the font falls back to the rest
+     * of its stack and the mail loads nothing from Google. Fonts the document
+     * declares itself (`metadata.fonts`) are always emitted. Default `true`.
+     */
+    webFonts?: boolean;
+}
+/**
+ * The options both engines compile with, in one place: the server's `mjml`
+ * and the browser's `mjml-browser` must receive the same ones, or their
+ * output differs by configuration rather than by build, and the parity test
+ * between them means nothing.
+ */
+declare function mjmlOptions(options?: CompileOptions): {
+    fonts?: {} | undefined;
+    ignoreIncludes: boolean;
+    validationLevel: "soft";
+    minify: boolean;
+};
+/**
+ * Turns an EmailTemplate into MJML markup. `MJMLCompiler` (server) and
+ * `compileInBrowser` (browser) both compile what this emits.
+ */
+declare class MjmlBuilder {
+    /**
+     * Set true while emitting a column with sub-columns. Causes generateHead
+     * to inject the responsive media query exactly once per template.
+     */
+    protected needsSubColumnStyles: boolean;
+    /** Set for the duration of one build in editor mode; see {@link BuildOptions}. */
+    protected editor: boolean;
+    /** `fragment` fenced as an editor addition, or nothing outside editor mode. */
+    protected ee(fragment: string): string;
+    /** The label of a ghost: what the node is, so the person can find and unhide it. */
+    private ghostText;
+    /**
+     * The MJML markup for a document, without compiling it to HTML.
+     */
+    toMJML(template: EmailTemplate, options?: BuildOptions): string;
+    /**
+     * Convert template to MJML markup
+     */
+    protected templateToMJML(template: EmailTemplate): string;
+    /**
+     * Generate MJML head section with all head components
+     * Supports: mj-title, mj-preview, mj-font, mj-breakpoint, mj-style
+     */
+    private generateHead;
+    /**
+     * Collect background-image CSS rules for all wrappers, sections and columns that have gradients.
+     * Returns a string of CSS rules to inject as a single mj-style block.
+     */
+    private collectGradientStyles;
+    /**
+     * Convert a wrapper to an `<mj-wrapper>` around its sections. The wrapper's
+     * attributes are MJML's own for `mj-wrapper`; the sections inside follow
+     * MJML's rules there (a full-width section inside a full-width wrapper
+     * renders at standard width, which the inspector explains).
+     */
+    private wrapperToMJML;
+    /** Background attributes shared by sections and wrappers: a gradient (with its Outlook fallback colour), or colour and image. */
+    private pushBackground;
+    /**
+     * Convert section to MJML
+     * Supports background images, full-width, and mj-group for non-stacking columns
+     */
+    private sectionToMJML;
+    /**
+     * Convert column to MJML
+     */
+    private columnToMJML;
+    /**
+     * Emit a group column as an mj-column wrapping a hand-built nested
+     * table inside an mj-raw island. The parent mj-section structure
+     * stays standard MJML; only the nested area escapes MJML's parser.
+     *
+     * The responsive media query (table.ee-sub-cols td.ee-sub-col) is
+     * injected once at document head via generateHead when the
+     * needsSubColumnStyles flag is set.
+     */
+    private subColumnsToMJML;
+    /**
+     * Convert block to MJML based on type
+     */
+    private blockToMJML;
+    /**
+     * Convert text block to MJML
+     *
+     * Note: MJML applies styles to the container <td>, but TipTap content
+     * (wrapped in <p> tags) doesn't inherit these styles. We solve this by
+     * wrapping the content in a <div> with explicit inline styles.
+     */
+    private textBlockToMJML;
+    /**
+     * Convert image block to MJML
+     */
+    private imageBlockToMJML;
+    /**
+     * Convert button block to MJML
+     */
+    private buttonBlockToMJML;
+    /**
+     * Convert divider block to MJML
+     */
+    private dividerBlockToMJML;
+    /**
+     * Convert spacer block to MJML
+     */
+    private spacerBlockToMJML;
+    /**
+     * Platform brand colors for social icons
+     */
+    private readonly SOCIAL_COLORS;
+    /**
+     * Get white SVG icon as data URI for a platform
+     * Uses clean, minimal SVGs optimized for email
+     */
+    private getSocialIconDataUri;
+    /**
+     * Convert social block to MJML using raw HTML table for reliable horizontal layout
+     * Uses styled anchor tags with background colors for full width control
+     */
+    private socialBlockToMJML;
+    /**
+     * Convert hero block to MJML
+     */
+    private heroBlockToMJML;
+    /**
+     * Convert accordion block to MJML
+     */
+    private accordionBlockToMJML;
+    /**
+     * Convert raw HTML block to MJML
+     */
+    private rawBlockToMJML;
+    /**
+     * Convert navbar block to MJML
+     */
+    private navbarBlockToMJML;
+    /**
+     * Convert carousel block to MJML
+     */
+    private carouselBlockToMJML;
+    /**
+     * Convert table block to MJML
+     */
+    private tableBlockToMJML;
+    /**
+     * Generate the locked header block.
+     *
+     * It used to render one client's company name and a logo from an image host;
+     * both are gone. What is left is a placeholder image slot. Keep this in step
+     * with `headerBlockDefinition` in `packages/blocks/src/branded/index.ts`:
+     * which of the two runs depends on how the registry is configured.
+     *
+     * The placeholder is a `data:` URI rather than an address on an image host,
+     * so a workspace whose `asset_policy` is `service_only` can still send a mail
+     * that contains this block.
+     */
+    private headerBlockToMJML;
+    /**
+     * Generate the locked footer block: the unsubscribe link and nothing else.
+     *
+     * It used to carry a copyright line naming one client's company. A locked
+     * block carries no props, so whoever sends the mail cannot correct a name
+     * that is not theirs; the line is gone rather than replaced with a fake one.
+     * Keep this in step with `footerBlockDefinition` in
+     * `packages/blocks/src/branded/index.ts`.
+     */
+    private footerBlockToMJML;
+}
+
+export { type AccordionBlock as A, type BuildOptions as B, type CompileOptions as C, DEFAULT_MJML_ATTRIBUTES as D, type EmailTemplate as E, type FontDefinition as F, type GradientStop as G, type HeaderBlock as H, type ImageBlock as I, type TextBlock as J, type ThemeColor as K, type TopLevelItem as L, MjmlBuilder as M, type NavbarBlock as N, addPx as O, allSections as P, base64Utf8 as Q, type RawBlock as R, type Section as S, type TableBlock as T, buildGradientCSS as U, encodeEditorData as V, type Wrapper as W, isWrapper as X, paddingWithGap as Y, textInlineStyles as Z, type CompileResult as a, EDITOR_MARKER as b, type Block as c, type BackgroundGradient as d, type MjmlHead as e, type AccordionItem as f, type BaseBlock as g, type ButtonBlock as h, type CarouselBlock as i, type CarouselImage as j, type Column as k, type DividerBlock as l, mjmlOptions as m, EDITOR_DATA_ATTRIBUTE as n, type ExtraAttributes as o, type FooterBlock as p, type HeroBlock as q, type NavbarLink as r, stripEditorMarkup as s, type SocialBlock as t, type SocialLink as u, type SpacerBlock as v, type Spacing as w, type SubColumn as x, type TemplateMetadata as y, type TemplateVersion as z };