@parathantl/react-email-editor 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -1,10 +1,33 @@
-import * as React$1 from 'react';
-import React__default, { ReactNode, ComponentType } from 'react';
+import * as react from 'react';
+import { ReactNode, ComponentType } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _tiptap_core from '@tiptap/core';
 import { Editor, Node } from '@tiptap/core';
 import * as _tiptap_extension_underline from '@tiptap/extension-underline';
 
+declare const DEFAULT_SOCIAL_PROPERTIES: SocialBlockProperties;
+declare const DEFAULT_BLOCK_PROPERTIES: {
+    [K in BlockType]: BlockPropertiesMap[K];
+};
+declare const DEFAULT_SECTION_PROPERTIES: SectionProperties;
+declare const DEFAULT_HEAD_METADATA: HeadMetadata;
+declare const DEFAULT_GLOBAL_STYLES: GlobalStyles;
+declare const DEFAULT_VARIABLE_CHIP_STYLE: VariableChipStyle;
+interface BlockDefinition {
+    type: BlockType;
+    label: string;
+    icon: string;
+    description: string;
+}
+declare const BLOCK_DEFINITIONS: BlockDefinition[];
+declare const DEFAULT_FONT_SIZES: string[];
+declare const FONT_OPTIONS: string[];
+declare const COLOR_PRESETS: string[];
+declare const COLUMN_LAYOUTS: {
+    label: string;
+    widths: string[];
+}[];
+
 type BlockType = 'text' | 'button' | 'image' | 'divider' | 'spacer' | 'social' | 'html' | 'video' | 'heading' | 'countdown' | 'menu' | 'hero';
 interface TextBlockProperties {
     content: string;
@@ -15,7 +38,7 @@ interface TextBlockProperties {
     padding: string;
     align: 'left' | 'center' | 'right' | 'justify';
     fontWeight: string;
-    textTransform: string;
+    textTransform: 'none' | 'uppercase' | 'lowercase' | 'capitalize';
     letterSpacing: string;
 }
 interface ButtonBlockProperties {
@@ -31,7 +54,7 @@ interface ButtonBlockProperties {
     align: 'left' | 'center' | 'right';
     width: string;
     fontWeight: string;
-    textTransform: string;
+    textTransform: 'none' | 'uppercase' | 'lowercase' | 'capitalize';
     letterSpacing: string;
 }
 interface ImageBlockProperties {
@@ -55,6 +78,7 @@ interface SpacerBlockProperties {
     height: string;
 }
 interface SocialElement {
+    id?: string;
     name: string;
     href: string;
     src?: string;
@@ -94,7 +118,7 @@ interface HeadingBlockProperties {
     fontWeight: string;
     padding: string;
     align: 'left' | 'center' | 'right' | 'justify';
-    textTransform: string;
+    textTransform: 'none' | 'uppercase' | 'lowercase' | 'capitalize';
     letterSpacing: string;
 }
 interface CountdownBlockProperties {
@@ -108,6 +132,7 @@ interface CountdownBlockProperties {
     align: 'left' | 'center' | 'right';
 }
 interface MenuItem {
+    id?: string;
     text: string;
     href: string;
 }
@@ -135,6 +160,8 @@ interface HeroBlockProperties {
     buttonBorderRadius: string;
     align: 'left' | 'center' | 'right';
     padding: string;
+    backgroundImage: string;
+    backgroundColor: string;
 }
 type BlockProperties = TextBlockProperties | ButtonBlockProperties | ImageBlockProperties | DividerBlockProperties | SpacerBlockProperties | SocialBlockProperties | HtmlBlockProperties | VideoBlockProperties | HeadingBlockProperties | CountdownBlockProperties | MenuBlockProperties | HeroBlockProperties;
 interface BlockPropertiesMap {
@@ -151,11 +178,17 @@ interface BlockPropertiesMap {
     menu: MenuBlockProperties;
     hero: HeroBlockProperties;
 }
-interface Block {
+interface Block<T extends BlockType = BlockType> {
     id: string;
-    type: BlockType;
+    type: T;
     properties: Record<string, any>;
 }
+/** A Block with type-safe properties, returned by narrowBlock */
+interface TypedBlock<T extends BlockType> extends Block<T> {
+    properties: BlockPropertiesMap[T];
+}
+/** Narrow a Block to a specific type for type-safe property access */
+declare function narrowBlock<T extends BlockType>(block: Block, type: T): block is TypedBlock<T>;
 interface Column {
     id: string;
     width: string;
@@ -193,7 +226,7 @@ interface EmailTemplate {
 interface Variable {
     key: string;
     icon?: string;
-    sample: string;
+    sample?: string;
     label?: string;
     group?: string;
 }
@@ -205,9 +238,9 @@ interface VariableChipStyle {
     borderRadius: string;
 }
 interface PersistenceAdapter {
-    save(key: string, template: EmailTemplate): void;
-    load(key: string): EmailTemplate | null;
-    remove(key: string): void;
+    save(key: string, template: EmailTemplate): void | Promise<void>;
+    load(key: string): EmailTemplate | null | Promise<EmailTemplate | null>;
+    remove(key: string): void | Promise<void>;
 }
 interface UploadOptions {
     context: string;
@@ -253,6 +286,10 @@ interface EditorState {
     history: EmailTemplate[];
     historyIndex: number;
     isDirty: boolean;
+    blockIndex: Map<string, {
+        sectionId: string;
+        columnId: string;
+    }>;
 }
 type EditorAction = {
     type: 'SET_TEMPLATE';
@@ -344,10 +381,29 @@ type EditorAction = {
     payload: {
         sectionId: string;
     };
+} | {
+    type: 'ADD_BLOCK_AND_SELECT';
+    payload: {
+        sectionId: string;
+        columnId: string;
+        block: Block;
+        index?: number;
+    };
+} | {
+    type: 'ADD_SECTION_WITH_BLOCK';
+    payload: {
+        section: Section;
+        block: Block;
+        index?: number;
+    };
+} | {
+    type: 'DESELECT_ALL';
 } | {
     type: 'UNDO';
 } | {
     type: 'REDO';
+} | {
+    type: 'PUSH_HISTORY';
 };
 interface EmailEditorProps {
     initialTemplate?: EmailTemplate;
@@ -357,16 +413,40 @@ interface EmailEditorProps {
     onChange?: (template: EmailTemplate) => void;
     onSave?: (mjml: string, html: string) => void;
     onReady?: () => void;
+    /** Called when custom variables are added or removed by the user. Receives all custom variables. */
+    onVariablesChange?: (customVariables: Variable[]) => void;
     /** Custom font family options for the rich text toolbar. Falls back to FONT_OPTIONS constant. */
     fontFamilies?: string[];
     /** Custom font size options for the rich text toolbar (e.g. ['12px', '14px', '16px']). Falls back to DEFAULT_FONT_SIZES constant. */
     fontSizes?: string[];
+    /** Custom block definitions for the sidebar palette. Override icons, labels, descriptions, or hide specific blocks. Falls back to BLOCK_DEFINITIONS constant. */
+    blockDefinitions?: BlockDefinition[];
     /** Key for auto-persisting the template. Different keys allow multiple editor instances to coexist. */
     persistenceKey?: string;
     /** Custom persistence adapter. Defaults to localStorage when persistenceKey is set. */
     persistenceAdapter?: PersistenceAdapter;
     className?: string;
     style?: React.CSSProperties;
+    /** Called when a block is added to the template */
+    onBlockAdd?: (block: Block, sectionId: string, columnId: string) => void;
+    /** Called when a block is removed from the template */
+    onBlockRemove?: (blockId: string, sectionId: string, columnId: string) => void;
+    /** Called when block properties are updated */
+    onBlockUpdate?: (blockId: string, properties: Partial<BlockProperties>) => void;
+    /** Called when a block is moved to a new position */
+    onBlockMove?: (blockId: string, toSectionId: string, toColumnId: string, toIndex: number) => void;
+    /** Called when a section is added to the template */
+    onSectionAdd?: (section: Section, index?: number) => void;
+    /** Called when a section is removed from the template */
+    onSectionRemove?: (sectionId: string) => void;
+    /** Called when a section is moved to a new position */
+    onSectionMove?: (sectionId: string, toIndex: number) => void;
+    /** Called when the selection changes */
+    onSelectionChange?: (selection: SelectionState) => void;
+    /** Called when a template is loaded via SET_TEMPLATE */
+    onTemplateLoad?: (template: EmailTemplate) => void;
+    /** Called when history state changes (undo/redo) */
+    onHistoryChange?: (canUndo: boolean, canRedo: boolean) => void;
 }
 interface EmailEditorRef {
     getMJML: () => string;
@@ -384,49 +464,107 @@ interface EmailEditorRef {
     clearPersisted: () => void;
 }
 
-declare const EmailEditor: React$1.ForwardRefExoticComponent<EmailEditorProps & React$1.RefAttributes<EmailEditorRef>>;
+declare const EmailEditor: react.ForwardRefExoticComponent<EmailEditorProps & react.RefAttributes<EmailEditorRef>>;
 
-interface EditorContextValue {
-    state: EditorState;
-    dispatch: React__default.Dispatch<EditorAction>;
-    /** All variables: pre-defined (props) + custom (user-created) */
+/** @deprecated Use focused hooks (useTemplateContext, useSelectionContext, etc.) instead */
+declare function useEditorState(): {
+    template: EmailTemplate;
+    isDirty: boolean;
+    activeTab: ActiveTab;
+    selection: SelectionState;
+    canUndo: boolean;
+    canRedo: boolean;
+};
+declare function useEditorDispatch(): React.Dispatch<EditorAction>;
+declare function useSelectedBlock(): Block | null;
+declare function useSelectedSection(): Section | null;
+declare function useEditorVariables(): {
     variables: Variable[];
-    /** Pre-defined variables from props (read-only) */
     predefinedVariables: Variable[];
-    /** User-created custom variables */
     customVariables: Variable[];
-    imageUploadAdapter?: ImageUploadAdapter;
-    setActiveEditor: (editor: Editor | null) => void;
-    getActiveEditor: () => Editor | null;
+    addCustomVariable: (variable: Variable) => void;
+    removeCustomVariable: (key: string) => void;
     insertVariable: (key: string) => boolean;
+    variableChipStyle: VariableChipStyle;
+    updateVariableChipStyle: (style: Partial<VariableChipStyle>) => void;
+};
+declare function useEditorFonts(): {
+    fontFamilies: string[];
+    fontSizes: string[];
+};
+declare function useImageAdapter(): {
+    imageUploadAdapter: ImageUploadAdapter | undefined;
+};
+
+declare function useDispatchContext(): React.Dispatch<EditorAction>;
+
+interface TemplateContextValue {
+    template: EmailTemplate;
+    isDirty: boolean;
+    activeTab: ActiveTab;
+}
+declare function useTemplateContext(): TemplateContextValue;
+
+declare function useSelectionContext(): SelectionState;
+
+interface ConfigContextValue {
+    variables: Variable[];
+    predefinedVariables: Variable[];
+    customVariables: Variable[];
+    imageUploadAdapter?: ImageUploadAdapter;
     addCustomVariable: (variable: Variable) => void;
     removeCustomVariable: (key: string) => void;
     variableChipStyle: VariableChipStyle;
     updateVariableChipStyle: (style: Partial<VariableChipStyle>) => void;
-    /** Font family options for the rich text toolbar */
     fontFamilies: string[];
-    /** Font size options for the rich text toolbar */
     fontSizes: string[];
-    /** Remove persisted template for the current key. No-op if no persistenceKey. */
     clearPersisted: () => void;
 }
-declare function useEditor(): EditorContextValue;
-declare function useEditorState(): EditorState;
-declare function useEditorDispatch(): React__default.Dispatch<EditorAction>;
-declare function useSelectedBlock(): Block | null;
-declare function useSelectedSection(): Section | null;
+declare function useConfigContext(): ConfigContextValue;
+
+interface MethodsContextValue {
+    setActiveEditor: (editor: Editor | null) => void;
+    getActiveEditor: () => Editor | null;
+    insertVariable: (key: string) => boolean;
+}
+declare function useMethodsContext(): MethodsContextValue;
+
+interface HistoryContextValue {
+    canUndo: boolean;
+    canRedo: boolean;
+}
+declare function useHistoryContext(): HistoryContextValue;
+
+type BlockIndex = Map<string, {
+    sectionId: string;
+    columnId: string;
+}>;
+
+declare function useBlockIndexContext(): BlockIndex;
+
 interface EditorProviderProps {
     children: ReactNode;
     initialTemplate?: EmailTemplate;
     variables?: Variable[];
     imageUploadAdapter?: ImageUploadAdapter;
     onChange?: (template: EmailTemplate) => void;
+    onVariablesChange?: (customVariables: Variable[]) => void;
     fontFamilies?: string[];
     fontSizes?: string[];
     persistenceKey?: string;
     persistenceAdapter?: PersistenceAdapter;
-}
-declare function EditorProvider({ children, initialTemplate, variables: predefinedVariables, imageUploadAdapter, onChange, fontFamilies: fontFamiliesProp, fontSizes: fontSizesProp, persistenceKey, persistenceAdapter, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
+    onBlockAdd?: (block: Block, sectionId: string, columnId: string) => void;
+    onBlockRemove?: (blockId: string, sectionId: string, columnId: string) => void;
+    onBlockUpdate?: (blockId: string, properties: Partial<BlockProperties>) => void;
+    onBlockMove?: (blockId: string, toSectionId: string, toColumnId: string, toIndex: number) => void;
+    onSectionAdd?: (section: Section, index?: number) => void;
+    onSectionRemove?: (sectionId: string) => void;
+    onSectionMove?: (sectionId: string, toIndex: number) => void;
+    onSelectionChange?: (selection: SelectionState) => void;
+    onTemplateLoad?: (template: EmailTemplate) => void;
+    onHistoryChange?: (canUndo: boolean, canRedo: boolean) => void;
+}
+declare function EditorProvider({ children, initialTemplate, variables: predefinedVariables, imageUploadAdapter, onChange, onVariablesChange, fontFamilies: fontFamiliesProp, fontSizes: fontSizesProp, persistenceKey, persistenceAdapter, onBlockAdd, onBlockRemove, onBlockUpdate, onBlockMove, onSectionAdd, onSectionRemove, onSectionMove, onSelectionChange, onTemplateLoad, onHistoryChange, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function parseMJML(mjmlString: string): EmailTemplate;
 
@@ -465,6 +603,27 @@ declare function groupVariables(variables: Variable[]): Map<string, Variable[]>;
 
 declare function sanitizeHTML(html: string): string;
 declare function escapeHTML(str: string): string;
+/**
+ * Returns true if the URL scheme is safe (http, https, mailto, tel, fragment, relative path).
+ * Rejects javascript:, data:, vbscript:, and other dangerous schemes.
+ */
+declare function isSafeURL(url: string): boolean;
+
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validate raw data as an EmailTemplate.
+ * Returns { valid, errors } with descriptive error messages.
+ */
+declare function validateTemplate(data: unknown): ValidationResult;
+/**
+ * Sanitize and coerce raw data into a valid EmailTemplate.
+ * Fixes common issues (missing globalStyles, headMetadata, malformed sections).
+ * Returns a safe-to-use template even if input is partially invalid.
+ */
+declare function sanitizeTemplate(data: unknown): EmailTemplate;
 
 /**
  * Default persistence adapter using localStorage.
@@ -480,36 +639,24 @@ declare const localStorageAdapter: PersistenceAdapter;
  * Adding a new block type requires only adding entries here (Open/Closed Principle).
  */
 
-declare function registerBlockRenderer(type: BlockType, component: ComponentType<{
+/**
+ * Register a block renderer. Accepts BlockType for built-in types, or any string for custom blocks.
+ */
+declare function registerBlockRenderer(type: BlockType | (string & {}), component: ComponentType<{
     block: Block;
 }>): void;
-declare function registerBlockProperties(type: BlockType, component: ComponentType<{
+/**
+ * Register a block properties panel. Accepts BlockType for built-in types, or any string for custom blocks.
+ */
+declare function registerBlockProperties(type: BlockType | (string & {}), component: ComponentType<{
     block: Block;
 }>): void;
-declare function registerBlockGenerator(type: BlockType, generator: (block: Block, indent: string) => string): void;
+/**
+ * Register a MJML generator. Accepts BlockType for built-in types, or any string for custom blocks.
+ */
+declare function registerBlockGenerator(type: BlockType | (string & {}), generator: (block: Block, indent: string) => string): void;
 declare function registerBlockParser(mjmlTag: string, parser: (el: Element) => Block): void;
+/** Returns set of all registered block types (built-in + custom). */
+declare function getRegisteredBlockTypes(): Set<string>;
 
-declare const DEFAULT_SOCIAL_PROPERTIES: SocialBlockProperties;
-declare const DEFAULT_BLOCK_PROPERTIES: {
-    [K in BlockType]: BlockPropertiesMap[K];
-};
-declare const DEFAULT_SECTION_PROPERTIES: SectionProperties;
-declare const DEFAULT_HEAD_METADATA: HeadMetadata;
-declare const DEFAULT_GLOBAL_STYLES: GlobalStyles;
-declare const DEFAULT_VARIABLE_CHIP_STYLE: VariableChipStyle;
-interface BlockDefinition {
-    type: BlockType;
-    label: string;
-    icon: string;
-    description: string;
-}
-declare const BLOCK_DEFINITIONS: BlockDefinition[];
-declare const DEFAULT_FONT_SIZES: string[];
-declare const FONT_OPTIONS: string[];
-declare const COLOR_PRESETS: string[];
-declare const COLUMN_LAYOUTS: {
-    label: string;
-    widths: string[];
-}[];
-
-export { type ActiveTab, BLOCK_DEFINITIONS, type Block, type BlockProperties, type BlockPropertiesMap, type BlockType, type BrowseResult, type ButtonBlockProperties, COLOR_PRESETS, COLUMN_LAYOUTS, type Column, type CountdownBlockProperties, DEFAULT_BLOCK_PROPERTIES, DEFAULT_FONT_SIZES, DEFAULT_GLOBAL_STYLES, DEFAULT_HEAD_METADATA, DEFAULT_SECTION_PROPERTIES, DEFAULT_SOCIAL_PROPERTIES, DEFAULT_VARIABLE_CHIP_STYLE, type DividerBlockProperties, type EditorAction, EditorProvider, type EditorState, EmailEditor, type EmailEditorProps, type EmailEditorRef, type EmailTemplate, FONT_OPTIONS, type GlobalStyles, type HeadMetadata, type HeroBlockProperties, type ImageBlockProperties, type ImageUploadAdapter, type MenuBlockProperties, type MenuItem, type PersistenceAdapter, type Section, type SectionProperties, type SelectionState, type SocialBlockProperties, type SocialElement, type SpacerBlockProperties, type TextBlockProperties, type TransformOptions, type UploadOptions, type UploadResult, type Variable, type VariableChipStyle, VariableNode, compileMJMLToHTML, escapeHTML, extractVariableKeys, generateBlockId, generateColumnId, generateId, generateMJML, generateSectionId, getExtensions, groupVariables, localStorageAdapter, parseMJML, registerBlockGenerator, registerBlockParser, registerBlockProperties, registerBlockRenderer, replaceVariables, sanitizeHTML, useEditor, useEditorDispatch, useEditorState, useSelectedBlock, useSelectedSection };
+export { type ActiveTab, BLOCK_DEFINITIONS, type Block, type BlockDefinition, type BlockProperties, type BlockPropertiesMap, type BlockType, type BrowseResult, type ButtonBlockProperties, COLOR_PRESETS, COLUMN_LAYOUTS, type Column, type CountdownBlockProperties, DEFAULT_BLOCK_PROPERTIES, DEFAULT_FONT_SIZES, DEFAULT_GLOBAL_STYLES, DEFAULT_HEAD_METADATA, DEFAULT_SECTION_PROPERTIES, DEFAULT_SOCIAL_PROPERTIES, DEFAULT_VARIABLE_CHIP_STYLE, type DividerBlockProperties, type EditorAction, EditorProvider, type EditorState, EmailEditor, type EmailEditorProps, type EmailEditorRef, type EmailTemplate, FONT_OPTIONS, type GlobalStyles, type HeadMetadata, type HeadingBlockProperties, type HeroBlockProperties, type HtmlBlockProperties, type ImageBlockProperties, type ImageUploadAdapter, type MenuBlockProperties, type MenuItem, type PersistenceAdapter, type Section, type SectionProperties, type SelectionState, type SocialBlockProperties, type SocialElement, type SpacerBlockProperties, type TextBlockProperties, type TransformOptions, type TypedBlock, type UploadOptions, type UploadResult, type ValidationResult, type Variable, type VariableChipStyle, VariableNode, type VideoBlockProperties, compileMJMLToHTML, escapeHTML, extractVariableKeys, generateBlockId, generateColumnId, generateId, generateMJML, generateSectionId, getExtensions, getRegisteredBlockTypes, groupVariables, isSafeURL, localStorageAdapter, narrowBlock, parseMJML, registerBlockGenerator, registerBlockParser, registerBlockProperties, registerBlockRenderer, replaceVariables, sanitizeHTML, sanitizeTemplate, useBlockIndexContext, useConfigContext, useDispatchContext, useEditorDispatch, useEditorFonts, useEditorState, useEditorVariables, useHistoryContext, useImageAdapter, useMethodsContext, useSelectedBlock, useSelectedSection, useSelectionContext, useTemplateContext, validateTemplate };