@marlinjai/email-editor-ui 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,514 @@
+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';
+
+/**
+ * What the editor tells the host when it asks for an image.
+ */
+interface ImageRequest {
+    /** The id of the block the image is for (or the section or wrapper, for a background image) */
+    blockId: string;
+    /** What is asking: a block type (`image`), or `section` or `wrapper` for a background image */
+    blockType: string;
+    /** The image URL the block currently shows, if any */
+    currentUrl?: string;
+    /** The alt text the block currently has, if any */
+    currentAlt?: string;
+}
+/**
+ * The image the host hands back: a URL the email can load (it must be
+ * publicly reachable from a recipient's mail client), and optional alt text.
+ */
+interface RequestedImage {
+    url: string;
+    alt?: string;
+}
+/**
+ * Called when the user asks to choose an image. Open your own picker or
+ * uploader, then resolve with the chosen image, or with `null` when the user
+ * cancels (the block is left unchanged). A rejected promise is shown to the
+ * user as an inline error next to the button, using the error's message.
+ */
+type OnRequestImage = (request: ImageRequest) => Promise<RequestedImage | null>;
+/**
+ * Called when somebody asks to keep a section for reuse. The editor has already
+ * asked for the name and checked it against `savedSectionNames`; what is handed
+ * over is a plain snapshot of the section, ids and all.
+ *
+ * Resolve when it is stored. A rejected promise is shown in the dialog, using
+ * the error's message, and the dialog stays open so the name is not lost.
+ *
+ * Without it no "Save as a section" action appears, rather than an action that
+ * fails: a host that cannot store one should not offer to.
+ */
+type OnSaveSection = (section: Record<string, unknown>, name: string) => Promise<void>;
+interface EditorHostHooks {
+    onRequestImage?: OnRequestImage;
+    onSaveSection?: OnSaveSection;
+    /**
+     * The names this workspace has already used, so the dialog can say that a
+     * name is taken before the save is attempted rather than after it comes back
+     * as a conflict.
+     */
+    savedSectionNames?: readonly string[];
+    /**
+     * The editor's root element. Dialogs portal into it rather than into
+     * `document.body`, so they stay inside the scoped stylesheet and inherit
+     * the theme tokens set on the root.
+     */
+    portalContainer?: HTMLElement | null;
+}
+declare function EditorHostProvider({ onRequestImage, onSaveSection, savedSectionNames, portalContainer, children, }: EditorHostHooks & {
+    children: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * The hooks the host supplied. Outside an editor every hook is undefined, so
+ * components fall back to their built-in behavior.
+ */
+declare function useEditorHost(): EditorHostHooks;
+
+interface EmailEditorProps {
+    /** Initial template data */
+    initialTemplate?: TemplateSnapshotIn;
+    /** Called when template changes */
+    onChange?: (template: TemplateSnapshotOut) => void;
+    /** Block registry for available block types */
+    blockRegistry: BlockRegistryImpl;
+    /** Pre-built template registry */
+    prebuiltRegistry?: PrebuiltTemplateRegistry;
+    /** Called when save button is clicked */
+    onSave?: () => void;
+    /** Called when export is requested */
+    onExport?: (template: TemplateSnapshotOut) => void;
+    /** Called when back button is clicked to navigate away from editor */
+    onNavigateBack?: () => void;
+    /**
+     * Supply images from the host's own picker or uploader. When set, the image
+     * block's inspector shows a "Choose image" button that calls it instead of a
+     * URL field. Resolve with `null` to cancel; a rejection is shown inline.
+     */
+    onRequestImage?: OnRequestImage;
+    /**
+     * Keep a section for reuse. When set, a selected section's controls carry a
+     * "Save as a section" action, which asks for a name and calls this. Without
+     * it no action appears, rather than one that fails.
+     */
+    onSaveSection?: OnSaveSection;
+    /** The names already saved, so the dialog can catch a clash before the save. */
+    savedSectionNames?: readonly string[];
+    /** Extra class names for the editor's root element (which carries `ee-root`) */
+    className?: string;
+    /**
+     * Inline styles for the editor's root element. Use it to set design tokens,
+     * e.g. `{ '--ee-accent': '#0f766e' }`. The editor fills its container's
+     * height, so give the container one.
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * EmailEditor - Main email editor component
+ *
+ * Uses MobX State Tree for instant visual feedback on property changes.
+ * MJML compilation only happens on export, not during editing.
+ */
+declare const EmailEditor: React.FunctionComponent<EmailEditorProps>;
+
+/**
+ * Provider component for the store
+ */
+declare const StoreProvider: Provider<RootStoreInstance | null>;
+/**
+ * Hook to access the full store
+ * @throws Error if used outside of StoreProvider
+ */
+declare function useStore(): RootStoreInstance;
+/**
+ * Hook to access just the template
+ */
+declare function useTemplate(): TemplateInstance;
+/**
+ * Hook to access just the editor UI store
+ */
+declare function useEditorUI(): EditorUIInstance;
+/**
+ * Hook to get the selected block (convenience)
+ */
+declare function useSelectedBlock(): BlockInstance | undefined;
+/**
+ * Hook to get the selected section (convenience)
+ */
+declare function useSelectedSection(): SectionInstance | undefined;
+/**
+ * Hook to get the selected column (convenience)
+ */
+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;
+
+interface SectionRendererProps {
+    section: SectionInstance;
+    sectionIndex: number;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+};
+
+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;
+};
+
+interface TextBlockProps {
+    block: BlockInstance;
+}
+/**
+ * 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;
+};
+
+interface ImageBlockProps {
+    block: BlockInstance;
+}
+/**
+ * ImageBlock - Renders an image block in the email preview
+ */
+declare const ImageBlock: (({ block }: ImageBlockProps) => React.JSX.Element) & {
+    displayName: string;
+};
+
+interface ButtonBlockProps {
+    block: BlockInstance;
+}
+/**
+ * ButtonBlock - Renders a button/CTA block in the email preview
+ */
+declare const ButtonBlock: (({ block }: ButtonBlockProps) => React.JSX.Element) & {
+    displayName: string;
+};
+
+interface DividerBlockProps {
+    block: BlockInstance;
+}
+/**
+ * DividerBlock - Renders a horizontal divider in the email preview
+ */
+declare const DividerBlock: (({ block }: DividerBlockProps) => React.JSX.Element) & {
+    displayName: string;
+};
+
+interface SpacerBlockProps {
+    block: BlockInstance;
+}
+/**
+ * SpacerBlock - Renders vertical spacing in the email preview
+ */
+declare const SpacerBlock: (({ block }: SpacerBlockProps) => React.JSX.Element) & {
+    displayName: string;
+};
+
+interface SocialBlockProps {
+    block: BlockInstance;
+}
+/**
+ * SocialBlock - Renders social media icons in the email preview
+ */
+declare const SocialBlock: (({ block }: SocialBlockProps) => React.JSX.Element) & {
+    displayName: string;
+};
+
+interface HeroBlockProps {
+    block: BlockInstance;
+}
+/**
+ * HeroBlock - Renders a hero section with background image
+ */
+declare const HeroBlock: (({ block }: HeroBlockProps) => React.JSX.Element) & {
+    displayName: string;
+};
+
+interface RawBlockProps {
+    block: BlockInstance;
+}
+/**
+ * RawBlock - Renders custom HTML content
+ */
+declare const RawBlock: (({ block }: RawBlockProps) => React.JSX.Element) & {
+    displayName: string;
+};
+
+interface PropertyInspectorProps {
+    onDeleteBlock?: (blockId: string) => void;
+}
+/**
+ * PropertyInspector - Property editor panel
+ *
+ * Updates MST models directly for instant visual feedback.
+ * No intermediate state or MJML recompilation needed.
+ */
+declare const PropertyInspector: React.FunctionComponent<PropertyInspectorProps>;
+
+/**
+ * Normalize spacing values to ensure valid CSS units.
+ *
+ * CSS ignores unitless values (except 0), so we auto-append "px" for bare numbers.
+ * MJML supports: px, % (em/rem have poor email client support)
+ *
+ * @example
+ * normalizeSpacingValue("10")    // "10px" - bare number gets px
+ * normalizeSpacingValue("10px")  // "10px" - already has unit
+ * normalizeSpacingValue("5%")    // "5%"   - percent is valid
+ * normalizeSpacingValue("0")     // "0"    - zero works without unit
+ * normalizeSpacingValue("")      // undefined - empty clears value
+ */
+declare function normalizeSpacingValue(value: string): string | undefined;
+/**
+ * Formatting toolbar for text editing
+ * Uses execCommand for contenteditable WYSIWYG editing
+ *
+ * Important: Uses onMouseDown with preventDefault to keep focus
+ * in the contenteditable text block while clicking buttons.
+ */
+declare function FormattingToolbar(): React.JSX.Element;
+/**
+ * Text input field
+ */
+declare function TextField({ label, value, onChange, placeholder, hint, error, }: {
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    /** A line under the field saying what it does. */
+    hint?: string;
+    /** Shown instead of the hint, and marks the field invalid. */
+    error?: string;
+}): React.JSX.Element;
+/**
+ * Theme color swatch type
+ */
+interface ThemeColorSwatch {
+    name: string;
+    value: string;
+}
+/**
+ * Color picker with text input and theme color swatches
+ */
+declare function ColorField({ label, value, onChange, allowEmpty, themeColors, }: {
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    allowEmpty?: boolean;
+    themeColors?: ThemeColorSwatch[];
+}): React.JSX.Element;
+/**
+ * Select dropdown field
+ */
+declare function SelectField({ label, value, options, onChange, }: {
+    label: string;
+    value: string;
+    options: string[];
+    onChange: (value: string) => void;
+}): React.JSX.Element;
+/**
+ * Text alignment buttons
+ */
+declare function AlignmentField({ value, onChange, }: {
+    value: string;
+    onChange: (value: string) => void;
+}): React.JSX.Element;
+/**
+ * Checkbox field
+ */
+declare function CheckboxField({ label, checked, onChange, disabled, hint, }: {
+    label: string;
+    checked: boolean;
+    onChange: () => void;
+    disabled?: boolean;
+    /** A line under the checkbox, e.g. why it is disabled. */
+    hint?: string;
+}): React.JSX.Element;
+/**
+ * 4-sided spacing input (top, right, bottom, left)
+ *
+ * Automatically normalizes values to ensure valid CSS units.
+ * Bare numbers like "10" become "10px".
+ */
+declare function SpacingField({ label, top, right, bottom, left, onChange, placeholders, hint, }: {
+    label: string;
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+    onChange: (side: 'top' | 'right' | 'bottom' | 'left', value: string | undefined) => void;
+    /** Placeholders per side, e.g. what the mail uses when a side is not set. */
+    placeholders?: Partial<Record<'top' | 'right' | 'bottom' | 'left', string>>;
+    hint?: string;
+}): React.JSX.Element;
+/**
+ * Range slider with value display
+ */
+declare function RangeField({ label, value, min, max, onChange, unit, }: {
+    label: string;
+    value: number;
+    min: number;
+    max: number;
+    onChange: (value: number) => void;
+    unit?: string;
+}): React.JSX.Element;
+/**
+ * Button group for selecting from options
+ */
+declare function ButtonGroupField({ label, value, options, onChange, }: {
+    label: string;
+    value: string | number;
+    options: (string | number)[];
+    onChange: (value: string | number) => void;
+}): React.JSX.Element;
+/**
+ * Gradient editor field
+ */
+declare function GradientField({ value, onChange, }: {
+    value: BackgroundGradient | undefined;
+    onChange: (gradient: BackgroundGradient | undefined) => void;
+}): React.JSX.Element;
+
+interface BlockPropertiesProps {
+    block: BlockInstance;
+    onDelete: () => void;
+}
+/**
+ * Main block properties panel - routes to type-specific panels
+ */
+declare const BlockProperties: React.FunctionComponent<BlockPropertiesProps>;
+
+interface SectionPropertiesProps {
+    section: SectionInstance;
+}
+/**
+ * Section properties panel
+ */
+declare const SectionProperties: React.FunctionComponent<SectionPropertiesProps>;
+
+interface ColumnPropertiesProps {
+    column: ColumnInstance;
+}
+/**
+ * Column properties panel
+ */
+declare const ColumnProperties: React.FunctionComponent<ColumnPropertiesProps>;
+
+interface SubColumnPropertiesProps {
+    subColumn: SubColumnInstance;
+    parentColumn: ColumnInstance;
+}
+declare const SubColumnProperties: React.FunctionComponent<SubColumnPropertiesProps>;
+
+interface ElementsPanelProps {
+    blocks: BlockDefinition[];
+}
+/**
+ * Panel showing draggable base elements (MJML blocks)
+ * Matches Mailjet's "Elements > Content" panel
+ */
+declare const ElementsPanel: React.FunctionComponent<ElementsPanelProps>;
+
+interface LayoutPanelProps {
+    templates: PrebuiltTemplate[];
+    onAddSection: (columns: 1 | 2 | 3) => void;
+    onAddPrebuilt: (template: PrebuiltTemplate) => void;
+    /** Adds a container (MJML mj-wrapper) around one empty section. */
+    onAddWrapper: () => void;
+}
+declare function LayoutPanel({ templates, onAddSection, onAddPrebuilt, onAddWrapper }: LayoutPanelProps): React.JSX.Element;
+
+declare const LayersPanel: React.FunctionComponent<object>;
+
+interface LeftSidebarProps {
+    blockRegistry: BlockRegistryImpl;
+    prebuiltRegistry?: PrebuiltTemplateRegistry;
+    onAddSection: (columnCount: 1 | 2 | 3) => void;
+    onAddPrebuilt: (template: PrebuiltTemplate) => void;
+    onAddWrapper: () => void;
+}
+declare const LeftSidebar: React.FunctionComponent<LeftSidebarProps>;
+
+declare const TemplateSettingsPanel: React.FunctionComponent<object>;
+
+interface DragOverlayContentProps {
+    item: {
+        type: 'block' | 'template';
+        id: string;
+        label: string;
+    };
+}
+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 };