@marlinjai/email-editor-ui 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import React, { Provider } from 'react';
-import { TemplateSnapshotIn, TemplateSnapshotOut, BlockRegistryImpl, PrebuiltTemplateRegistry, RootStoreInstance, EditorUIInstance, BlockInstance, ColumnInstance, SectionInstance, TemplateInstance, BackgroundGradient, SubColumnInstance, BlockDefinition, PrebuiltTemplate } from '@marlinjai/email-editor-core';
+import { TemplateSnapshotIn, TemplateSnapshotOut, BlockRegistryImpl, PrebuiltTemplateRegistry, RootStoreInstance, EditorUIInstance, BlockInstance, ColumnInstance, SectionInstance, TemplateInstance, EmailTemplate, CompileResult, TextBlock, BackgroundGradient, SubColumnInstance, BlockDefinition, PrebuiltTemplate } from '@marlinjai/email-editor-core';
 
 /**
  * What the editor tells the host when it asks for an image.
@@ -71,6 +71,12 @@ interface EmailEditorProps {
     initialTemplate?: TemplateSnapshotIn;
     /** Called when template changes */
     onChange?: (template: TemplateSnapshotOut) => void;
+    /**
+     * The messages of the host's most recent server compile, when it refused
+     * something. Shown as a badge in the toolbar; the canvas itself is a browser
+     * compile that cannot run the service's asset policy.
+     */
+    policyErrors?: string[];
     /** Block registry for available block types */
     blockRegistry: BlockRegistryImpl;
     /** Pre-built template registry */
@@ -142,168 +148,172 @@ declare function useSelectedSection(): SectionInstance | undefined;
  */
 declare function useSelectedColumn(): ColumnInstance | undefined;
 
-interface EmailRendererProps {
-    /** Additional class names */
-    className?: string;
-}
-/**
- * EmailRenderer - Root renderer for email templates
- *
- * This is the main preview component that renders the entire email template
- * using React components instead of MJML compilation.
- *
- * Key benefits:
- * - Instant updates (<16ms) on property changes
- * - Fine-grained reactivity (only changed blocks re-render)
- * - No iframe needed
- * - MJML compilation only happens on export
- */
-declare const EmailRenderer: (({ className }: EmailRendererProps) => React.JSX.Element) & {
-    displayName: string;
-};
-/**
- * Hook to get the email renderer width
- */
-declare function usePreviewWidth(): number;
+declare const DESKTOP_WIDTH = 600;
+declare const MOBILE_WIDTH = 375;
+/** The frame runs nothing: same origin so the overlay can measure and hit-test, no scripts so nothing a Raw block brought along can run. */
+declare const FRAME_SANDBOX = "allow-same-origin";
+declare const CompiledCanvas: React.FunctionComponent<object>;
 
-interface SectionRendererProps {
-    section: SectionInstance;
-    sectionIndex: number;
+type NodeKind = 'block' | 'column' | 'subcolumn' | 'section' | 'wrapper';
+interface NodeRef {
+    id: string;
+    kind: NodeKind;
 }
-/**
- * SectionRenderer - Renders a section with its columns
- *
- * Key features:
- * - Table-based layout for email compatibility
- * - Section selection and hover states
- * - Column distribution
- * - Background styling
- */
-declare const SectionRenderer: (({ section, sectionIndex }: SectionRendererProps) => React.JSX.Element) & {
-    displayName: string;
-};
-
-interface ColumnRendererProps {
-    column: ColumnInstance;
-    section: SectionInstance;
-    columnIndex: number;
+/** A node's box, in the frame document's coordinates (the frame never scrolls, so these are also offsets from the frame's top-left). */
+interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
 }
-/**
- * ColumnRenderer - Renders a column within a section
- *
- * Key features:
- * - Renders blocks in order
- * - Handles column selection
- * - Shows drop zones during drag
- * - Applies column styling
- */
-declare const ColumnRenderer: (({ column, section, columnIndex }: ColumnRendererProps) => React.JSX.Element) & {
-    displayName: string;
-};
+/** Every node id in the document and what it is, so an `el-<id>` class in the frame resolves to a node the store knows. */
+declare function nodeIndex(template: TemplateInstance): Map<string, NodeKind>;
+/** The node an element belongs to: itself or its nearest ancestor that carries an `el-<id>` of the document, or a tagged Raw block's markup. */
+declare function nodeFromElement(element: Element | null, index: Map<string, NodeKind>): NodeRef | null;
+/**
+ * A Raw block's markup is emitted verbatim, between `<!--ee:raw:id-->` and
+ * `<!--/ee:raw:id-->` in editor mode, because MJML drops `css-class` on
+ * `mj-raw`. This tags every element between the two comments with the id so
+ * hit-testing and measuring treat them as the block. Display-side only.
+ */
+declare function tagRawBlocks(doc: Document): void;
+/** The elements that make up a node: one for most, several for a Raw block. */
+declare function elementsOf(doc: Document, id: string): Element[];
+/** The box of every node that rendered, in frame coordinates. Nodes with nothing on screen (a hidden column, empty raw markup) are absent. */
+declare function measureNodes(doc: Document, index: Map<string, NodeKind>): Map<string, Box>;
+/** The `<head>` of a compiled document, for deciding whether a morph can apply the next one. */
+declare function headOf(html: string): string;
+/**
+ * Put a compiled document into the frame. The first document, or one whose
+ * head changed (fonts, styles), loads through `srcdoc`; any other is morphed
+ * into the live body so images do not reflash and the scroll position holds.
+ * Returns how it was applied; after a reload the caller waits for `load`.
+ */
+declare function applyHtml(iframe: HTMLIFrameElement, html: string, previous: string | null): 'reload' | 'morph';
+/**
+ * Nothing in the frame may navigate or submit: the overlay owns pointer
+ * events, and this is the second guard, for the moments it lets them through
+ * (in-place editing) and for keyboard focus reaching an anchor. Capture phase,
+ * so a handler in the mail could not run first even if scripts were allowed.
+ */
+declare function guardNavigation(doc: Document): void;
 
-interface BlockRendererProps {
-    block: BlockInstance;
-    /** Whether this block is in inline editing mode */
-    isEditing?: boolean;
-}
-/**
- * BlockRenderer - Routes blocks to their specific renderer components
- *
- * Key features:
- * - Wraps blocks with selection/hover UI
- * - Handles click to select
- * - Shows hidden block placeholder
- * - Routes to appropriate block renderer
- */
-declare const BlockRenderer: (({ block, isEditing }: BlockRendererProps) => React.JSX.Element) & {
-    displayName: string;
+/** The data a band carries; the editor's drop handler reads it off `over.data`. */
+type DropTarget = {
+    columnId: string;
+    index: number;
+} | {
+    subColumnId: string;
+    index: number;
 };
-
-interface TextBlockProps {
-    block: BlockInstance;
+interface Band {
+    id: string;
+    target: DropTarget;
+    x: number;
+    y: number;
+    width: number;
 }
-/**
- * TextBlock - Renders a text block with inline WYSIWYG editing
- *
- * Key implementation details:
- * - Uses contenteditable for direct text editing when selected
- * - Does NOT use dangerouslySetInnerHTML when editing (causes cursor reset)
- * - Syncs content to MST only on blur (not on every keystroke)
- * - Stops keyboard event propagation to prevent block deletion on backspace
- */
-declare const TextBlock: (({ block }: TextBlockProps) => React.JSX.Element) & {
-    displayName: string;
-};
+/** The bands of a document, from its nodes' boxes. Pure, so it is testable without dnd-kit. */
+declare function bandsFor(template: any, boxes: Map<string, Box>): Band[];
 
-interface ImageBlockProps {
-    block: BlockInstance;
+interface CompileSchedulerOptions<S, R> {
+    /** The compile itself. May be synchronous or return a promise. */
+    compile: (snapshot: S) => R | Promise<R>;
+    /** Called with a result that is newer than every result applied before it. */
+    onResult: (result: R, version: number) => void;
+    /** Called when a compile throws or rejects; the version is dropped. */
+    onError?: (error: unknown, version: number) => void;
+    /** Quiet time after the last schedule before compiling. Default 100. */
+    delayMs?: number;
 }
-/**
- * ImageBlock - Renders an image block in the email preview
- */
-declare const ImageBlock: (({ block }: ImageBlockProps) => React.JSX.Element) & {
-    displayName: string;
-};
-
-interface ButtonBlockProps {
-    block: BlockInstance;
+interface CompileScheduler<S> {
+    /** A new snapshot: compiles after the quiet time, superseding any earlier pending one. */
+    schedule(snapshot: S): number;
+    /** Compile the pending snapshot now, without waiting for the quiet time. */
+    flush(): void;
+    /** The version of the newest snapshot scheduled so far (0 before the first). */
+    readonly version: number;
+    /** The version of the newest result applied so far (0 before the first). */
+    readonly applied: number;
+    dispose(): void;
 }
-/**
- * ButtonBlock - Renders a button/CTA block in the email preview
- */
-declare const ButtonBlock: (({ block }: ButtonBlockProps) => React.JSX.Element) & {
-    displayName: string;
-};
+declare function createCompileScheduler<S, R>(options: CompileSchedulerOptions<S, R>): CompileScheduler<S>;
 
-interface DividerBlockProps {
-    block: BlockInstance;
+interface CompiledDocument {
+    /** Monotonic; a later document always has a higher version. */
+    version: number;
+    html: string;
+    /** MJML's soft-validation messages, when any. */
+    errors?: string[];
 }
-/**
- * DividerBlock - Renders a horizontal divider in the email preview
- */
-declare const DividerBlock: (({ block }: DividerBlockProps) => React.JSX.Element) & {
-    displayName: string;
+type CompileStatus = {
+    kind: 'loading';
+} | {
+    kind: 'ready';
+} | {
+    kind: 'failed';
+    message: string;
 };
-
-interface SpacerBlockProps {
-    block: BlockInstance;
-}
-/**
- * SpacerBlock - Renders vertical spacing in the email preview
- */
-declare const SpacerBlock: (({ block }: SpacerBlockProps) => React.JSX.Element) & {
-    displayName: string;
+type Compile = (template: EmailTemplate, options: {
+    editor: boolean;
+}) => CompileResult | Promise<CompileResult>;
+/** Tests only: swap the loader. */
+declare function setBrowserCompilerLoader(loader: () => Promise<Compile>): void;
+/** The browser compiler, loaded once per page and shared by every caller. */
+declare function browserCompiler(): Promise<Compile>;
+/** The browser compiler once it has loaded, null before; failures stay null (the canvas reports them). */
+declare function useBrowserCompiler(): Compile | null;
+declare function useCompiledDocument(template: TemplateInstance, hold: boolean, delayMs?: number): {
+    document: CompiledDocument | null;
+    status: CompileStatus;
+    retry: () => void;
 };
 
-interface SocialBlockProps {
-    block: BlockInstance;
-}
-/**
- * SocialBlock - Renders social media icons in the email preview
- */
-declare const SocialBlock: (({ block }: SocialBlockProps) => React.JSX.Element) & {
-    displayName: string;
-};
+declare function SectionThumbnail({ section, width, height, className }: {
+    section: Record<string, unknown>;
+    width: number;
+    height: number;
+    className?: string;
+}): React.JSX.Element;
 
-interface HeroBlockProps {
-    block: BlockInstance;
-}
+/** The `contenteditable` element of the in-place edit in progress, or null. */
+declare function activeEditingHost(): HTMLElement | null;
 /**
- * HeroBlock - Renders a hero section with background image
+ * Whether a pointer press at `target` belongs to the edit rather than ending
+ * it: the formatting toolbar and any dialog it opens carry `data-ee-keeps-edit`.
  */
-declare const HeroBlock: (({ block }: HeroBlockProps) => React.JSX.Element) & {
-    displayName: string;
-};
+declare function keepsEdit(target: EventTarget | null): boolean;
 
-interface RawBlockProps {
-    block: BlockInstance;
-}
 /**
- * RawBlock - Renders custom HTML content
- */
-declare const RawBlock: (({ block }: RawBlockProps) => React.JSX.Element) & {
-    displayName: string;
-};
+ * The element whose innerHTML is the block's content. MJML renders an
+ * `mj-text` as `<td class="el-text el-<id>"><div style=...>CONTENT</div></td>`;
+ * when the block carries inline styles the compiler wraps CONTENT in one more
+ * `<div style>`, by the rule `textInlineStyles` states.
+ */
+declare function editableFor(doc: Document, block: {
+    id: string;
+} & Partial<Pick<TextBlock, 'align' | 'color' | 'fontSize' | 'fontFamily' | 'lineHeight'>>): HTMLElement | null;
+interface InlineEdit {
+    /** The content as it was when editing began. */
+    readonly original: string;
+    /** What is in the element now. */
+    current(): string;
+    /** Store the content if it changed, without ending the edit. */
+    sync(): void;
+    /** Store the content if it changed and end the edit. */
+    commit(): void;
+    /** Put the original content back and end the edit. */
+    cancel(): void;
+    /** Whether this edit is still live. */
+    readonly active: boolean;
+}
+interface InlineEditHandlers {
+    /** Content to store; called on every sync or commit whose content differs from the last stored one. */
+    onChange: (content: string) => void;
+    /** The edit ended, by commit, cancel or a press elsewhere. */
+    onEnd: () => void;
+}
+declare function beginInlineEdit(element: HTMLElement, handlers: InlineEditHandlers): InlineEdit;
 
 interface PropertyInspectorProps {
     onDeleteBlock?: (blockId: string) => void;
@@ -332,10 +342,12 @@ declare const PropertyInspector: React.FunctionComponent<PropertyInspectorProps>
 declare function normalizeSpacingValue(value: string): string | undefined;
 /**
  * Formatting toolbar for text editing
- * Uses execCommand for contenteditable WYSIWYG editing
+ * Uses execCommand for contenteditable WYSIWYG editing, on the document the
+ * edited text lives in (the canvas frame).
  *
  * Important: Uses onMouseDown with preventDefault to keep focus
- * in the contenteditable text block while clicking buttons.
+ * in the contenteditable text block while clicking buttons, and carries
+ * `data-ee-keeps-edit` so a press on it does not end the in-place edit.
  */
 declare function FormattingToolbar(): React.JSX.Element;
 /**
@@ -511,4 +523,4 @@ interface DragOverlayContentProps {
 }
 declare function DragOverlayContent({ item }: DragOverlayContentProps): React.JSX.Element;
 
-export { AlignmentField, BlockProperties, BlockRenderer, ButtonBlock, ButtonGroupField, CheckboxField, ColorField, ColumnProperties, ColumnRenderer, DividerBlock, DragOverlayContent, type EditorHostHooks, EditorHostProvider, ElementsPanel, EmailEditor, type EmailEditorProps, EmailRenderer, FormattingToolbar, GradientField, HeroBlock, ImageBlock, type ImageRequest, LayersPanel, LayoutPanel, LeftSidebar, type OnRequestImage, type OnSaveSection, PropertyInspector, RangeField, RawBlock, type RequestedImage, SectionProperties, SectionRenderer, SelectField, SocialBlock, SpacerBlock, SpacingField, StoreProvider, SubColumnProperties, TemplateSettingsPanel, TextBlock, TextField, normalizeSpacingValue, useEditorHost, useEditorUI, usePreviewWidth, useSelectedBlock, useSelectedColumn, useSelectedSection, useStore, useTemplate };
+export { AlignmentField, type Band, BlockProperties, type Box, ButtonGroupField, CheckboxField, ColorField, ColumnProperties, type CompileScheduler, type CompileSchedulerOptions, type CompileStatus, CompiledCanvas, type CompiledDocument, DESKTOP_WIDTH, DragOverlayContent, type DropTarget, type EditorHostHooks, EditorHostProvider, ElementsPanel, EmailEditor, type EmailEditorProps, FRAME_SANDBOX, FormattingToolbar, GradientField, type ImageRequest, type InlineEdit, type InlineEditHandlers, LayersPanel, LayoutPanel, LeftSidebar, MOBILE_WIDTH, type NodeKind, type NodeRef, type OnRequestImage, type OnSaveSection, PropertyInspector, RangeField, type RequestedImage, SectionProperties, SectionThumbnail, SelectField, SpacingField, StoreProvider, SubColumnProperties, TemplateSettingsPanel, TextField, activeEditingHost, applyHtml, bandsFor, beginInlineEdit, browserCompiler, createCompileScheduler, editableFor, elementsOf, guardNavigation, headOf, keepsEdit, measureNodes, nodeFromElement, nodeIndex, normalizeSpacingValue, setBrowserCompilerLoader, tagRawBlocks, useBrowserCompiler, useCompiledDocument, useEditorHost, useEditorUI, useSelectedBlock, useSelectedColumn, useSelectedSection, useStore, useTemplate };