react-email-studio 3.4.0 → 3.8.0

package/dist/index.d.cts

@@ -131,11 +131,14 @@ type EmailDocumentSettings = {
     color?: string;
     responsive?: boolean;
     rtl?: boolean;
-    /** Canvas chrome + full editor settings snapshot for lossless studio JSON export/import. */
+    /** Content card inner padding (editor `settings.padding`). */
+    contentPadding?: number;
+    /** Content card corner radius (editor `settings.borderRadius`). */
+    contentBorderRadius?: number;
+    /** Studio snapshot for round-trip with the visual editor (settings + editor chrome). */
     _reactEmailStudio?: {
         contentPadding?: number;
         contentBorderRadius?: number;
-        /** Full `ReactEmailEditor` settings object (merged on load after canonical fields). */
         editorSettings?: Record<string, unknown>;
     };
 };
@@ -144,19 +147,37 @@ type RowLayout = {
     gap?: number;
     stackOnMobile?: boolean;
     align?: "left" | "center" | "right";
+    /** Editor layout preset key (e.g. `layout2`, `custom`) — optional on `email_document` rows. */
+    preset?: string;
+    /** Column width ratios; length should match `columns`. */
+    ratios?: number[];
 };
+/** Row shell on `email_document` (editor field names). */
+type RowProps = {
+    bgColor?: string;
+    bgImage?: string;
+    bgRepeat?: string;
+    bgSize?: string;
+    bgPosition?: string;
+    bgGradient?: {
+        angle?: number;
+        colors?: [string, string, string];
+        stops?: [number, number, number];
+    } | null;
+    padding?: Padding;
+    borderRadius?: number;
+    borderWidth?: number;
+    borderColor?: string;
+    textAlign?: "left" | "center" | "right" | "justify";
+};
+/** Legacy row shell (`backgroundColor`, …) — import only. */
 type RowStyles = {
     backgroundColor?: string;
     backgroundImage?: string;
     backgroundRepeat?: string;
     backgroundSize?: string;
     backgroundPosition?: string;
-    /** 3-stop linear gradient (editor-specific extension). */
-    backgroundGradient?: {
-        angle?: number;
-        colors?: [string, string, string];
-        stops?: [number, number, number];
-    };
+    backgroundGradient?: RowProps["bgGradient"];
     padding?: Padding;
     borderRadius?: number;
     borderWidth?: number;
@@ -174,6 +195,18 @@ type ColumnBorderRadius = number | {
     br?: number;
     bl?: number;
 };
+/** Column shell on `email_document` (editor field names). */
+type ColumnProps = {
+    padding?: Padding;
+    bgColor?: string;
+    bgImage?: string;
+    bgRepeat?: string;
+    bgSize?: string;
+    bgPosition?: string;
+    bgGradient?: RowProps["bgGradient"];
+    borderRadius?: ColumnBorderRadius;
+};
+/** Legacy column shell — import only. */
 type ColumnStyles = {
     padding?: Padding;
     backgroundColor?: string;
@@ -181,28 +214,27 @@ type ColumnStyles = {
     backgroundRepeat?: string;
     backgroundSize?: string;
     backgroundPosition?: string;
-    /** 3-stop linear gradient (editor-specific extension). */
-    backgroundGradient?: {
-        angle?: number;
-        colors?: [string, string, string];
-        stops?: [number, number, number];
-    };
-    /** Uniform px or per-corner (matches block border radius in the editor). */
+    backgroundGradient?: RowProps["bgGradient"];
     borderRadius?: ColumnBorderRadius;
 };
 type BlockBase = {
     id?: string;
     type: string;
-    content?: Record<string, unknown>;
+    /** Payload: object for most blocks; plain HTML string for `type: "html"`. */
+    content?: Record<string, unknown> | string;
+    /** Full editor block props (export + preferred import). */
+    props?: Record<string, unknown>;
+    /** Legacy block styling — import only when `props` is absent. */
     styles?: Record<string, unknown>;
     behavior?: Record<string, unknown>;
     responsive?: Record<string, unknown>;
-    /** Full editor block props for lossless export/import (react-email-studio). */
-    props?: Record<string, unknown>;
 };
 type EmailDocumentColumn = {
     id?: string;
     layout?: ColumnLayout;
+    /** Column surface (padding, backgrounds, radius). */
+    props?: ColumnProps;
+    /** Legacy column shell — import only. */
     styles?: ColumnStyles;
     blocks?: BlockBase[];
 };
@@ -210,9 +242,12 @@ type EmailDocumentRow = {
     id?: string;
     type?: "row";
     layout?: RowLayout;
+    /** Row shell (padding, backgrounds). */
+    props?: RowProps;
+    /** Legacy row shell — import only. */
     styles?: RowStyles;
     columns?: EmailDocumentColumn[];
-    /** Internal row fields (`preset`, `ratios`, `columnStyles`, …) without `cells` — merged on load. */
+    /** Editor row snapshot (`preset`, `ratios`, column props, …) for round-trip. */
     _reactEmailStudio?: {
         row?: Record<string, unknown>;
     };
@@ -220,11 +255,18 @@ type EmailDocumentRow = {
 type EmailDocument = {
     type: "email_document";
     settings?: EmailDocumentSettings;
+    /** Flat root blocks (optional interchange; `rows` is the primary LMS/export shape). */
+    blocks?: BlockBase[];
+    /** Layout rows with `columns[].blocks[]` (primary import/export shape). */
     rows?: EmailDocumentRow[];
     globalStyles?: Record<string, unknown>;
     responsive?: Record<string, unknown>;
 };
 
+/** Coerce fragment / array input into `email_document` before normalize. */
+declare function coerceEmailDocumentInput(input: unknown): unknown;
+/** Normalize input and return `email_document` in LMS/export shape (`rows[]` + `_reactEmailStudio`). */
+declare function canonicalizeEmailDocument(input: unknown): EmailDocument | null;
 /** Re-export for consumers typing `jsonToHtml` options. */
 type JsonToHtmlOptions = EmailHtmlOptions;
 /**
@@ -233,6 +275,23 @@ type JsonToHtmlOptions = EmailHtmlOptions;
  */
 declare function jsonToHtml(designInput: unknown, opts?: JsonToHtmlOptions): string;
 
+/**
+ * Pull usable HTML from a full document (`<!DOCTYPE` / `<html>`) or a fragment string.
+ */
+declare function extractHtmlForDesign(html: string): string;
+/**
+ * Wrap HTML (fragment or full email/page document) in a minimal `email_document`
+ * with one row, one column, and a single **html** block — suitable for `loadJson`.
+ *
+ * @returns `null` when there is no non-empty HTML after extraction/normalization.
+ */
+declare function htmlToEmailDesignTemplate(html: string): EmailDocument | null;
+/**
+ * HTML fragment or full document → `email_document` JSON string (for `loadJson` / storage).
+ * Returns `""` when there is no non-empty HTML after extraction.
+ */
+declare function htmlToJson(html: string, pretty?: boolean): string;
+
 /** Theme color tokens (subset used by the editor chrome). */
 type ThemeColors = (typeof THEMES)["light"];
 /** Known `options` keys for {@link ReactEmailEditor} — callers may pass extra keys; these are what the editor reads. */
@@ -263,8 +322,11 @@ type ReactEmailEditorOptions = EmailHtmlOptions & {
         paletteGroupLabels?: Partial<Record<BlockPaletteGroupKey, string>>;
     };
 };
+type LoadJsonOptions = {
+    mode?: "replace" | "append";
+};
 interface ReactEmailEditorRef {
-    loadJson(input: string | Record<string, unknown>): void;
+    loadJson(input: string | Record<string, unknown>, options?: LoadJsonOptions): void;
     /** Calls `cb` with the design as a JSON string (new `email_document` schema). */
     exportJson(cb: (json: string) => void, pretty?: boolean): void;
 }
@@ -286,20 +348,9 @@ type ReactEmailEditorProps = {
 };
 declare const ReactEmailEditor: react.ForwardRefExoticComponent<ReactEmailEditorProps & react.RefAttributes<ReactEmailEditorRef>> & {
     jsonToHtml: typeof jsonToHtml;
+    htmlToJson: typeof htmlToJson;
 };
 
-/**
- * Pull usable HTML from a full document (`<!DOCTYPE` / `<html>`) or a fragment string.
- */
-declare function extractHtmlForDesign(html: string): string;
-/**
- * Wrap HTML (fragment or full email/page document) in a minimal `email_document`
- * with one row, one column, and a single **html** block — suitable for `loadJson`.
- *
- * @returns `null` when there is no non-empty HTML after extraction/normalization.
- */
-declare function htmlToEmailDesignTemplate(html: string): EmailDocument | null;
-
 declare function utf8ToBase64(raw: string): string;
 declare function base64ToUtf8(b64: string): string;
 
@@ -427,4 +478,4 @@ declare const DEVICES: ({
 })[];
 declare function PreviewModal({ html, contentWidth, rowCount, blockCount, editorZoom, locale, initialDevice, initialMobileVariant, onClose, C, title, secondaryActionLabel, onSecondaryAction, }: EmailPreviewModalProps): react_jsx_runtime.JSX.Element;
 
-export { type BlockBase, type EmailDocument, type EmailDocumentColumn, type EmailDocumentRow, type EmailDocumentSettings, type EmailHtmlOptions, PreviewModal as EmailPreviewModal, type EmailPreviewModalProps, type JsonToHtmlOptions, type MobilePreviewVariant, ReactEmailEditor, type ReactEmailEditorOptions, type ReactEmailEditorProps, type ReactEmailEditorRef, base64ToUtf8, DEVICES as emailPreviewDevices, extractHtmlForDesign, htmlToEmailDesignTemplate, jsonToHtml, utf8ToBase64 };
+export { type BlockBase, type ColumnProps, type ColumnStyles, type EmailDocument, type EmailDocumentColumn, type EmailDocumentRow, type EmailDocumentSettings, type EmailHtmlOptions, PreviewModal as EmailPreviewModal, type EmailPreviewModalProps, type JsonToHtmlOptions, type LoadJsonOptions, type MobilePreviewVariant, ReactEmailEditor, type ReactEmailEditorOptions, type ReactEmailEditorProps, type ReactEmailEditorRef, type RowProps, type RowStyles, base64ToUtf8, canonicalizeEmailDocument, coerceEmailDocumentInput, DEVICES as emailPreviewDevices, extractHtmlForDesign, htmlToEmailDesignTemplate, htmlToJson, jsonToHtml, utf8ToBase64 };

package/dist/index.d.ts

@@ -131,11 +131,14 @@ type EmailDocumentSettings = {
     color?: string;
     responsive?: boolean;
     rtl?: boolean;
-    /** Canvas chrome + full editor settings snapshot for lossless studio JSON export/import. */
+    /** Content card inner padding (editor `settings.padding`). */
+    contentPadding?: number;
+    /** Content card corner radius (editor `settings.borderRadius`). */
+    contentBorderRadius?: number;
+    /** Studio snapshot for round-trip with the visual editor (settings + editor chrome). */
     _reactEmailStudio?: {
         contentPadding?: number;
         contentBorderRadius?: number;
-        /** Full `ReactEmailEditor` settings object (merged on load after canonical fields). */
         editorSettings?: Record<string, unknown>;
     };
 };
@@ -144,19 +147,37 @@ type RowLayout = {
     gap?: number;
     stackOnMobile?: boolean;
     align?: "left" | "center" | "right";
+    /** Editor layout preset key (e.g. `layout2`, `custom`) — optional on `email_document` rows. */
+    preset?: string;
+    /** Column width ratios; length should match `columns`. */
+    ratios?: number[];
 };
+/** Row shell on `email_document` (editor field names). */
+type RowProps = {
+    bgColor?: string;
+    bgImage?: string;
+    bgRepeat?: string;
+    bgSize?: string;
+    bgPosition?: string;
+    bgGradient?: {
+        angle?: number;
+        colors?: [string, string, string];
+        stops?: [number, number, number];
+    } | null;
+    padding?: Padding;
+    borderRadius?: number;
+    borderWidth?: number;
+    borderColor?: string;
+    textAlign?: "left" | "center" | "right" | "justify";
+};
+/** Legacy row shell (`backgroundColor`, …) — import only. */
 type RowStyles = {
     backgroundColor?: string;
     backgroundImage?: string;
     backgroundRepeat?: string;
     backgroundSize?: string;
     backgroundPosition?: string;
-    /** 3-stop linear gradient (editor-specific extension). */
-    backgroundGradient?: {
-        angle?: number;
-        colors?: [string, string, string];
-        stops?: [number, number, number];
-    };
+    backgroundGradient?: RowProps["bgGradient"];
     padding?: Padding;
     borderRadius?: number;
     borderWidth?: number;
@@ -174,6 +195,18 @@ type ColumnBorderRadius = number | {
     br?: number;
     bl?: number;
 };
+/** Column shell on `email_document` (editor field names). */
+type ColumnProps = {
+    padding?: Padding;
+    bgColor?: string;
+    bgImage?: string;
+    bgRepeat?: string;
+    bgSize?: string;
+    bgPosition?: string;
+    bgGradient?: RowProps["bgGradient"];
+    borderRadius?: ColumnBorderRadius;
+};
+/** Legacy column shell — import only. */
 type ColumnStyles = {
     padding?: Padding;
     backgroundColor?: string;
@@ -181,28 +214,27 @@ type ColumnStyles = {
     backgroundRepeat?: string;
     backgroundSize?: string;
     backgroundPosition?: string;
-    /** 3-stop linear gradient (editor-specific extension). */
-    backgroundGradient?: {
-        angle?: number;
-        colors?: [string, string, string];
-        stops?: [number, number, number];
-    };
-    /** Uniform px or per-corner (matches block border radius in the editor). */
+    backgroundGradient?: RowProps["bgGradient"];
     borderRadius?: ColumnBorderRadius;
 };
 type BlockBase = {
     id?: string;
     type: string;
-    content?: Record<string, unknown>;
+    /** Payload: object for most blocks; plain HTML string for `type: "html"`. */
+    content?: Record<string, unknown> | string;
+    /** Full editor block props (export + preferred import). */
+    props?: Record<string, unknown>;
+    /** Legacy block styling — import only when `props` is absent. */
     styles?: Record<string, unknown>;
     behavior?: Record<string, unknown>;
     responsive?: Record<string, unknown>;
-    /** Full editor block props for lossless export/import (react-email-studio). */
-    props?: Record<string, unknown>;
 };
 type EmailDocumentColumn = {
     id?: string;
     layout?: ColumnLayout;
+    /** Column surface (padding, backgrounds, radius). */
+    props?: ColumnProps;
+    /** Legacy column shell — import only. */
     styles?: ColumnStyles;
     blocks?: BlockBase[];
 };
@@ -210,9 +242,12 @@ type EmailDocumentRow = {
     id?: string;
     type?: "row";
     layout?: RowLayout;
+    /** Row shell (padding, backgrounds). */
+    props?: RowProps;
+    /** Legacy row shell — import only. */
     styles?: RowStyles;
     columns?: EmailDocumentColumn[];
-    /** Internal row fields (`preset`, `ratios`, `columnStyles`, …) without `cells` — merged on load. */
+    /** Editor row snapshot (`preset`, `ratios`, column props, …) for round-trip. */
     _reactEmailStudio?: {
         row?: Record<string, unknown>;
     };
@@ -220,11 +255,18 @@ type EmailDocumentRow = {
 type EmailDocument = {
     type: "email_document";
     settings?: EmailDocumentSettings;
+    /** Flat root blocks (optional interchange; `rows` is the primary LMS/export shape). */
+    blocks?: BlockBase[];
+    /** Layout rows with `columns[].blocks[]` (primary import/export shape). */
     rows?: EmailDocumentRow[];
     globalStyles?: Record<string, unknown>;
     responsive?: Record<string, unknown>;
 };
 
+/** Coerce fragment / array input into `email_document` before normalize. */
+declare function coerceEmailDocumentInput(input: unknown): unknown;
+/** Normalize input and return `email_document` in LMS/export shape (`rows[]` + `_reactEmailStudio`). */
+declare function canonicalizeEmailDocument(input: unknown): EmailDocument | null;
 /** Re-export for consumers typing `jsonToHtml` options. */
 type JsonToHtmlOptions = EmailHtmlOptions;
 /**
@@ -233,6 +275,23 @@ type JsonToHtmlOptions = EmailHtmlOptions;
  */
 declare function jsonToHtml(designInput: unknown, opts?: JsonToHtmlOptions): string;
 
+/**
+ * Pull usable HTML from a full document (`<!DOCTYPE` / `<html>`) or a fragment string.
+ */
+declare function extractHtmlForDesign(html: string): string;
+/**
+ * Wrap HTML (fragment or full email/page document) in a minimal `email_document`
+ * with one row, one column, and a single **html** block — suitable for `loadJson`.
+ *
+ * @returns `null` when there is no non-empty HTML after extraction/normalization.
+ */
+declare function htmlToEmailDesignTemplate(html: string): EmailDocument | null;
+/**
+ * HTML fragment or full document → `email_document` JSON string (for `loadJson` / storage).
+ * Returns `""` when there is no non-empty HTML after extraction.
+ */
+declare function htmlToJson(html: string, pretty?: boolean): string;
+
 /** Theme color tokens (subset used by the editor chrome). */
 type ThemeColors = (typeof THEMES)["light"];
 /** Known `options` keys for {@link ReactEmailEditor} — callers may pass extra keys; these are what the editor reads. */
@@ -263,8 +322,11 @@ type ReactEmailEditorOptions = EmailHtmlOptions & {
         paletteGroupLabels?: Partial<Record<BlockPaletteGroupKey, string>>;
     };
 };
+type LoadJsonOptions = {
+    mode?: "replace" | "append";
+};
 interface ReactEmailEditorRef {
-    loadJson(input: string | Record<string, unknown>): void;
+    loadJson(input: string | Record<string, unknown>, options?: LoadJsonOptions): void;
     /** Calls `cb` with the design as a JSON string (new `email_document` schema). */
     exportJson(cb: (json: string) => void, pretty?: boolean): void;
 }
@@ -286,20 +348,9 @@ type ReactEmailEditorProps = {
 };
 declare const ReactEmailEditor: react.ForwardRefExoticComponent<ReactEmailEditorProps & react.RefAttributes<ReactEmailEditorRef>> & {
     jsonToHtml: typeof jsonToHtml;
+    htmlToJson: typeof htmlToJson;
 };
 
-/**
- * Pull usable HTML from a full document (`<!DOCTYPE` / `<html>`) or a fragment string.
- */
-declare function extractHtmlForDesign(html: string): string;
-/**
- * Wrap HTML (fragment or full email/page document) in a minimal `email_document`
- * with one row, one column, and a single **html** block — suitable for `loadJson`.
- *
- * @returns `null` when there is no non-empty HTML after extraction/normalization.
- */
-declare function htmlToEmailDesignTemplate(html: string): EmailDocument | null;
-
 declare function utf8ToBase64(raw: string): string;
 declare function base64ToUtf8(b64: string): string;
 
@@ -427,4 +478,4 @@ declare const DEVICES: ({
 })[];
 declare function PreviewModal({ html, contentWidth, rowCount, blockCount, editorZoom, locale, initialDevice, initialMobileVariant, onClose, C, title, secondaryActionLabel, onSecondaryAction, }: EmailPreviewModalProps): react_jsx_runtime.JSX.Element;
 
-export { type BlockBase, type EmailDocument, type EmailDocumentColumn, type EmailDocumentRow, type EmailDocumentSettings, type EmailHtmlOptions, PreviewModal as EmailPreviewModal, type EmailPreviewModalProps, type JsonToHtmlOptions, type MobilePreviewVariant, ReactEmailEditor, type ReactEmailEditorOptions, type ReactEmailEditorProps, type ReactEmailEditorRef, base64ToUtf8, DEVICES as emailPreviewDevices, extractHtmlForDesign, htmlToEmailDesignTemplate, jsonToHtml, utf8ToBase64 };
+export { type BlockBase, type ColumnProps, type ColumnStyles, type EmailDocument, type EmailDocumentColumn, type EmailDocumentRow, type EmailDocumentSettings, type EmailHtmlOptions, PreviewModal as EmailPreviewModal, type EmailPreviewModalProps, type JsonToHtmlOptions, type LoadJsonOptions, type MobilePreviewVariant, ReactEmailEditor, type ReactEmailEditorOptions, type ReactEmailEditorProps, type ReactEmailEditorRef, type RowProps, type RowStyles, base64ToUtf8, canonicalizeEmailDocument, coerceEmailDocumentInput, DEVICES as emailPreviewDevices, extractHtmlForDesign, htmlToEmailDesignTemplate, htmlToJson, jsonToHtml, utf8ToBase64 };