email-builder-online 4.0.0 → 4.1.0

package/README.md

@@ -1,789 +1,792 @@
-# email-builder-online
-
-Powerful, modern email builder with drag-and-drop blocks, live preview, and HTML export. Built with React and Material UI, distributed as a React component and as a Web Component so it can be embedded in other frameworks (Nuxt 3, Next.js, SvelteKit, etc.). Compatible with React 18 and 19.
-
-🚀 **[Live Demo](https://emailbuilder.online/)**
-
-## Features
-
-- **Drag-and-drop blocks**: Text (Rich Text Editor), Heading, Image, Button, Columns, Divider, Spacer, HTML, Social Media, Container
-- **Editor and Preview tabs** with responsive screen sizes (Desktop/Mobile)
-- **Undo/Redo** and keyboard shortcuts
-- **HTML export** and copy-to-clipboard helpers
-- **CSS size guard** for email client compatibility
-- **Dark mode** support
-- **AI features** for text (rewrite, grammar, continue, tone) and image generation
-- **Image gallery** integration with custom image provider support
-- **Internationalization (i18n)** with English, Spanish, and Italian support
-- **Works as React component or Web Component** - embed in any framework (Nuxt 3, Next.js, SvelteKit, Vue, etc.)
-- **Built with TypeScript** for better developer experience
-- **Responsive design** that works on mobile and desktop
-
-## Installation
-
-Install the package:
-
-```bash
-npm i email-builder-online
-# or
-yarn add email-builder-online
-# or
-pnpm add email-builder-online
-```
-
-> **Note:** All dependencies (React, Material UI, i18n, drag-and-drop, etc.) are bundled with the package — no extra installs needed.
-
-### Peer dependencies (React / React-DOM)
-
-**`react` and `react-dom` must be the same major/minor version** (e.g. both 18.x or both 19.x). Mixing versions (e.g. react@18 with react-dom@19) can cause runtime errors such as "Cannot read properties of undefined (reading 'S')".
-
-If your project uses **Vite**, add this to your `vite.config` to avoid multiple instances of React (recommended on Windows and in monorepos):
-
-```ts
-export default defineConfig({
-  resolve: {
-    dedupe: ['react', 'react-dom', 'react-dom/client'],
-  },
-  // ...
-});
-```
-
-Add the stylesheet (required):
-
-```ts
-// React / Vite / Nuxt / Next
-import 'email-builder-online/style.css';
-```
-
-## AI Features
-
-The builder supports AI-powered features for both text and image blocks, controlled by a single `enableAI` prop.
-
-### Text AI
-
-When `enableAI` is `true`, the rich text editor (NotionText) shows AI actions in the bubble menu toolbar and slash menu:
-- Rewrite, grammar check, continue writing
-- Tone adjustments: shorter, descriptive, detailed, friendly, professional
-
-Text AI uses the `onAIRequest` callback to process requests. You provide the backend integration:
-
-```tsx
-<EmailBuilder
-  enableAI={true}
-  onAIRequest={async ({ text, content, action, blockId }) => {
-    const response = await fetch('/api/ai', {
-      method: 'POST',
-      body: JSON.stringify({ text, content, action }),
-      headers: { 'Content-Type': 'application/json' },
-    });
-    const data = await response.json();
-    return data.processedContent;
-  }}
-/>
-```
-
-### Image AI Generation
-
-When `enableAI` is `true`, image blocks and background image inputs show a "Generate with AI" button that opens a dialog for prompt-based image generation.
-
-#### Events
-
-The image AI generation uses a custom event system:
-
-**`request-ai-image`** - Fired when the user submits a prompt to generate an image
-
-```tsx
-window.addEventListener('request-ai-image', (event: CustomEvent) => {
-  const prompt = event.detail; // string: the user's prompt
-
-  // Call your AI image generation API
-  const imageUrl = await generateImage(prompt);
-
-  // Respond with the generated image
-  window.dispatchEvent(
-    new CustomEvent('generated-image', {
-      detail: { url: imageUrl, success: true },
-    })
-  );
-});
-```
-
-**`store-ai-image`** - Fired when the user confirms and inserts the generated image
-
-```tsx
-window.addEventListener('store-ai-image', (event: CustomEvent) => {
-  const imageUrl = event.detail; // string: URL of the image to store
-  // Persist the image to your storage if needed
-});
-```
-
-**`generated-image`** - Dispatch this event to return the generated image to the builder
-
-```tsx
-// Success
-window.dispatchEvent(
-  new CustomEvent('generated-image', {
-    detail: { url: 'https://example.com/generated.png', success: true },
-  })
-);
-
-// Error
-window.dispatchEvent(
-  new CustomEvent('generated-image', {
-    detail: { url: null, success: false, error: { code: 500, message: 'Generation failed' } },
-  })
-);
-```
-
-## Custom Image Provider
-
-You can integrate your own image selector/gallery by passing a React component through the `customImageProvider` prop. This component will be rendered at the top of the image input panel, allowing users to select images from your custom source.
-
-### Events
-
-The custom image provider can listen to and dispatch the following events:
-
-#### Listening to Events
-
-**`email-builder-image-panel-opened`** - Fired when an Image block is selected/opened in the editor
-
-```tsx
-window.addEventListener('email-builder-image-panel-opened', (event: CustomEvent) => {
-  const { blockId, currentImageUrl, alt } = event.detail;
-  // You can use this to highlight the current image in your gallery
-  // or load additional data based on the current selection
-});
-```
-
-Event detail properties:
-
-- `blockId` (string): The ID of the selected image block
-- `currentImageUrl` (string | null): The URL of the currently selected image, or null if no image is set
-- `alt` (string | null): The alt text of the current image, or null if not set
-
-#### Dispatching Events
-
-**`email-builder-set-image`** - Dispatch this event to set an image in the currently selected block
-
-```tsx
-window.dispatchEvent(
-  new CustomEvent('email-builder-set-image', {
-    detail: imageUrl, // string: URL of the image to set
-  })
-);
-```
-
-### Complete Example
-
-```tsx
-import React, { useEffect, useState } from 'react';
-import { EmailBuilder } from 'email-builder-online';
-
-function MyImageGallery() {
-  const [currentImageUrl, setCurrentImageUrl] = useState<string | null>(null);
-
-  useEffect(() => {
-    // Listen for when the image panel opens
-    const handlePanelOpened = (event: CustomEvent) => {
-      const { currentImageUrl } = event.detail;
-      setCurrentImageUrl(currentImageUrl);
-    };
-
-    window.addEventListener('email-builder-image-panel-opened', handlePanelOpened);
-
-    return () => {
-      window.removeEventListener('email-builder-image-panel-opened', handlePanelOpened);
-    };
-  }, []);
-
-  const handleImageSelect = (imageUrl: string) => {
-    // Dispatch event to set the image
-    window.dispatchEvent(
-      new CustomEvent('email-builder-set-image', {
-        detail: imageUrl,
-      })
-    );
-  };
-
-  return (
-    <div>
-      <h4>My Custom Gallery</h4>
-      {currentImageUrl && <p style={{ fontSize: '12px', color: '#666' }}>Current: {currentImageUrl}</p>}
-      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '8px' }}>
-        <img
-          src="https://example.com/image1.jpg"
-          onClick={() => handleImageSelect('https://example.com/image1.jpg')}
-          style={{
-            cursor: 'pointer',
-            width: '100%',
-            border: currentImageUrl === 'https://example.com/image1.jpg' ? '2px solid blue' : 'none',
-          }}
-        />
-        {/* More images... */}
-      </div>
-    </div>
-  );
-}
-
-export default function Page() {
-  return (
-    <EmailBuilder
-      customImageProvider={<MyImageGallery />}
-      // ... other props
-    />
-  );
-}
-```
-
-> **Live Example**: Check out the working implementation in `packages/editor-sample/src/components/SampleImageGallery.tsx` and see it in action in the demo app.
-
-## Custom Merge Tags
-
-You can provide your own merge tags that will appear in the text editor's merge tag menu. Pass an array of tags or a complete group configuration:
-
-### Simple Array of Tags
-
-```tsx
-import { EmailBuilder, MergeTag } from 'email-builder-online';
-
-const myMergeTags: MergeTag[] = [
-  {
-    label: 'First Name',
-    value: '[first_name]',
-  },
-  {
-    label: 'Last Name',
-    value: '[last_name]',
-  },
-  {
-    label: 'Company',
-    value: '[company]',
-  },
-  {
-    type: 'divider', // Add a divider
-  },
-  {
-    label: 'Custom Link',
-    value: '{custom_link}Click here{/custom_link}',
-  },
-];
-
-export default function Page() {
-  return (
-    <EmailBuilder
-      mergeTags={myMergeTags}
-      // ... other props
-    />
-  );
-}
-```
-
-### Complete Group with Custom Icons
-
-```tsx
-import { EmailBuilder, MergeTagGroup } from 'email-builder-online';
-import { User, Building, Mail } from 'lucide-react'; // or any icon library
-
-const myMergeTagGroup: MergeTagGroup = {
-  label: 'My Custom Tags',
-  icon: <Mail />,
-  children: [
-    {
-      label: 'First Name',
-      value: '[first_name]',
-      icon: <User />,
-    },
-    {
-      label: 'Company Name',
-      value: '[company]',
-      icon: <Building />,
-    },
-    {
-      type: 'divider',
-    },
-    {
-      label: 'Verification Link',
-      value: '{verify}Verify Account{/verify}',
-      icon: <Mail />,
-    },
-  ],
-};
-
-export default function Page() {
-  return (
-    <EmailBuilder
-      mergeTags={myMergeTagGroup}
-      // ... other props
-    />
-  );
-}
-```
-
-## Programmatic Image Loading
-
-You can load images programmatically using the ref:
-
-```tsx
-import { useRef } from 'react';
-import { EmailBuilder, EmailBuilderRef } from 'email-builder-online';
-
-export default function Page() {
-  const emailBuilderRef = useRef<EmailBuilderRef>(null);
-
-  const handleSelectFromMyGallery = (imageUrl: string, blockId: string) => {
-    // Set image URL for a specific block
-    emailBuilderRef.current?.setImageUrl(blockId, imageUrl);
-  };
-
-  return (
-    <EmailBuilder
-      ref={emailBuilderRef}
-      customImageProvider={<MyCustomGallery onSelect={handleSelectFromMyGallery} />}
-    />
-  );
-}
-```
-
-### Using with Custom Image Provider Events
-
-You can combine the ref approach with the event system for a more robust solution:
-
-```tsx
-import { useRef, useEffect, useState } from 'react';
-import { EmailBuilder, EmailBuilderRef } from 'email-builder-online';
-
-function MyCustomGallery() {
-  const [currentBlockId, setCurrentBlockId] = useState<string | null>(null);
-  const [currentImageUrl, setCurrentImageUrl] = useState<string | null>(null);
-
-  useEffect(() => {
-    const handlePanelOpened = (event: CustomEvent) => {
-      const { blockId, currentImageUrl } = event.detail;
-      setCurrentBlockId(blockId);
-      setCurrentImageUrl(currentImageUrl);
-    };
-
-    window.addEventListener('email-builder-image-panel-opened', handlePanelOpened);
-    return () => window.removeEventListener('email-builder-image-panel-opened', handlePanelOpened);
-  }, []);
-
-  const handleImageSelect = (imageUrl: string) => {
-    // Use the event system to set the image
-    window.dispatchEvent(
-      new CustomEvent('email-builder-set-image', {
-        detail: imageUrl,
-      })
-    );
-  };
-
-  return (
-    <div>
-      <h4>Select Image</h4>
-      {currentImageUrl && <p>Current: {currentImageUrl}</p>}
-      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '8px' }}>
-        {/* Your image gallery */}
-      </div>
-    </div>
-  );
-}
-
-export default function Page() {
-  const emailBuilderRef = useRef<EmailBuilderRef>(null);
-
-  // Alternative: Use ref method directly
-  const handleSelectFromGallery = (imageUrl: string, blockId: string) => {
-    emailBuilderRef.current?.setImageUrl(blockId, imageUrl);
-  };
-
-  return <EmailBuilder ref={emailBuilderRef} customImageProvider={<MyCustomGallery />} />;
-}
-```
-
-## Available Blocks
-
-The email builder includes the following drag-and-drop blocks:
-
-- **Text** - Rich text editor with formatting options (uses CustomEditor)
-- **Notion Text** - Advanced rich text editor with Notion-like editing experience
-- **WYSIWYG** - What-You-See-Is-What-You-Get rich text editor
-- **Heading** - Heading block for titles and subtitles
-- **Image** - Image block with link support
-- **Button** - Call-to-action button with customizable styling
-- **Columns** - Multi-column layout container
-- **Divider** - Horizontal divider/separator line
-- **Spacer** - Vertical spacing block
-- **Avatar** - Profile picture/avatar image
-- **HTML** - Raw HTML block for custom code
-- **Social Media** - Social media icons with links
-- **Container** - Container block for grouping content
-
-## Backward Compatibility
-
-The email builder automatically migrates legacy blocks to ensure compatibility with older templates:
-
-- **CustomEditor blocks** → Automatically converted to **NotionText**
-- **Wysiwyg blocks** → Automatically converted to **NotionText**
-- **Avatar blocks** → Automatically converted to **Image** (circular style maps to pill shape)
-
-This migration happens automatically when loading a document, so templates created before the introduction of the NotionText block will continue to work seamlessly. The migration preserves all content and styling while enabling the new editing features.
-
-## Usage
-
-There are three ways to use the builder:
-
-### 1) As a React component with Ref (recommended for programmatic control)
-
-Use a ref to control saving and access the document programmatically:
-
-```tsx
-import React, { useRef, useState, useEffect } from 'react';
-import { EmailBuilder, EmailBuilderRef, TEditorConfiguration, MergeTag } from 'email-builder-online';
-import 'email-builder-online/style.css';
-
-// Custom Image Gallery Component
-function MyImageGallery() {
-  const images = ['https://example.com/image1.jpg', 'https://example.com/image2.jpg', 'https://example.com/image3.jpg'];
-
-  const handleImageSelect = (imageUrl: string) => {
-    window.dispatchEvent(
-      new CustomEvent('email-builder-set-image', {
-        detail: imageUrl,
-      })
-    );
-  };
-
-  return (
-    <div>
-      <h4>My Custom Gallery</h4>
-      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '8px' }}>
-        {images.map((img, idx) => (
-          <img
-            key={idx}
-            src={img}
-            onClick={() => handleImageSelect(img)}
-            style={{ cursor: 'pointer', width: '100%', borderRadius: '4px' }}
-          />
-        ))}
-      </div>
-    </div>
-  );
-}
-
-// Custom Merge Tags
-const customMergeTags: MergeTag[] = [
-  {
-    label: 'First Name',
-    value: '[first_name]',
-  },
-  {
-    label: 'Last Name',
-    value: '[last_name]',
-  },
-  {
-    label: 'Company',
-    value: '[company]',
-  },
-  {
-    type: 'divider',
-  },
-  {
-    label: 'Verification Link',
-    value: '{verify}Verify your account{/verify}',
-  },
-];
-
-export default function Page() {
-  const emailBuilderRef = useRef<EmailBuilderRef>(null);
-  const [document, setDocument] = useState<TEditorConfiguration | null>(null);
-
-  // Load saved document on mount
-  useEffect(() => {
-    const saved = localStorage.getItem('draft');
-    if (saved) {
-      setDocument(JSON.parse(saved));
-    }
-  }, []);
-
-  const handleSave = () => {
-    if (emailBuilderRef.current) {
-      const document = emailBuilderRef.current.save();
-      // Send to your backend
-      fetch('/api/save', {
-        method: 'POST',
-        body: JSON.stringify(document),
-        headers: { 'Content-Type': 'application/json' },
-      });
-    }
-  };
-
-  const handleExportHtml = () => {
-    if (emailBuilderRef.current) {
-      const html = emailBuilderRef.current.getHtml();
-      // Download HTML file or send to backend
-      const blob = new Blob([html], { type: 'text/html' });
-      const url = URL.createObjectURL(blob);
-      const a = document.createElement('a');
-      a.href = url;
-      a.download = 'email.html';
-      a.click();
-      URL.revokeObjectURL(url);
-    }
-  };
-
-  const handleSendEmail = async () => {
-    if (emailBuilderRef.current) {
-      const html = emailBuilderRef.current.getHtml();
-      // Send email via your backend
-      await fetch('/api/send-email', {
-        method: 'POST',
-        body: JSON.stringify({ html }),
-        headers: { 'Content-Type': 'application/json' },
-      });
-    }
-  };
-
-  return (
-    <div style={{ height: '100vh' }}>
-      <button onClick={handleSave}>Save</button>
-      <button onClick={handleExportHtml}>Export HTML</button>
-      <button onClick={handleSendEmail}>Send Email</button>
-      <EmailBuilder
-        ref={emailBuilderRef}
-        data={document}
-        onAutoSave={(doc) => localStorage.setItem('draft', JSON.stringify(doc))}
-        customImageProvider={<MyImageGallery />}
-        mergeTags={customMergeTags}
-        primaryColor="#0d9488"
-        secondaryColor="#0ea5a6"
-        locale="en"
-        height="calc(100vh - 80px)"
-      />
-    </div>
-  );
-}
-```
-
-**Ref Methods:**
-
-The `EmailBuilderRef` exposes the following methods:
-
-- `getDocument(): TEditorConfiguration` - Returns the current editor document
-- `setDocument(document: TEditorConfiguration): void` - Replaces the current document
-- `save(): TEditorConfiguration` - Flushes pending changes, calls `onSave` (if provided) and returns the document
-- `getHtml(): string` - Returns the rendered HTML for the current document
-- `setImageUrl(blockId: string, url: string): void` - Sets the URL of an image block with the given ID and updates the document
-
-### 2) As a React component (basic usage)
-
-```tsx
-import React from 'react';
-import { EmailBuilder } from 'email-builder-online';
-import 'email-builder-online/style.css';
-
-export default function Page() {
-  return (
-    <div style={{ height: '100vh' }}>
-      <EmailBuilder
-        primaryColor="#0d9488"
-        secondaryColor="#0ea5a6"
-        darkMode={false}
-        stickyHeader
-        locale="en"
-        height="calc(100vh - 80px)"
-      />
-    </div>
-  );
-}
-```
-
-### 3) As a Web Component (works in Nuxt 3, Vue, Svelte, plain HTML)
-
-For Web Component usage, the component auto-registers in browser environments. Here's how to use it in different frameworks:
-
-#### Nuxt 3 Example
-
-1. Register the email builder component:
-
-```ts
-// plugins/email-builder.client.ts
-import { registerEmailBuilder } from 'email-builder-online';
-import 'email-builder-online/style.css';
-
-export default defineNuxtPlugin(() => {
-  // Register the web component
-  registerEmailBuilder('email-builder');
-});
-```
-
-#### Vanilla JavaScript Example
-
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <link rel="stylesheet" href="path/to/email-builder-online/style.css" />
-    <script src="path/to/email-builder-online/dist/index.umd.js"></script>
-  </head>
-  <body>
-    <script>
-      // Register the web component
-      window.EmailBuilder.registerEmailBuilder('email-builder');
-    </script>
-
-    <email-builder></email-builder>
-  </body>
-</html>
-```
-
-Then use it anywhere in your templates (wrap in `<ClientOnly>` for Nuxt):
-
-```vue
-<template>
-  <ClientOnly>
-    <email-builder
-      primary-color="#0d9488"
-      secondary-color="#0ea5a6"
-      dark-mode="false"
-      sticky-header="true"
-      locale="en"
-      height="calc(100vh - 80px)"
-    />
-  </ClientOnly>
-</template>
-```
-
-For Vue/Nuxt, you can silence unknown element warnings by marking the tag as a custom element:
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  vue: {
-    compilerOptions: {
-      isCustomElement: (tag) => tag === 'email-builder',
-    },
-  },
-  css: ['email-builder-online/style.css'],
-});
-```
-
-**Notes on SSR and dependencies:**
-
-- The Web Component wrapper is registered only on the client. Use a client-only plugin in SSR frameworks.
-- React and ReactDOM are peer dependencies even for the Web Component. Install them in your app or use a bundler that provides them. React 18 and 19 are supported.
-- i18n dependencies (`i18next`, `react-i18next`, `i18next-browser-languagedetector`) are required for internationalization support and must be installed in your project.
-
-## Custom Editor Standalone
-
-The package also ships the `CustomEditorInputStandalone` component so the rich text block can be embedded outside of the full builder experience.
-
-### React
-
-```tsx
-import { useState } from 'react';
-import { CustomEditorInputStandalone } from 'email-builder-online';
-import 'email-builder-online/style.css';
-
-export default function CustomEditorExample() {
-  const [value, setValue] = useState('<p>Write your custom content here…</p>');
-
-  return (
-    <CustomEditorInputStandalone
-      initialData={value}
-      onChange={setValue}
-      editorBackgroundColor="#ffffff"
-      editorColorDefault="#1f2937"
-      fontFamily="MODERN_SANS"
-      lineHeight={1.6}
-    />
-  );
-}
-```
-
-### Web Component
-
-```ts
-import { registerCustomEditorInput } from 'email-builder-online';
-import 'email-builder-online/style.css';
-
-if (typeof window !== 'undefined') {
-  registerCustomEditorInput('custom-editor'); // default is "custom-editor-input"
-}
-```
-
-## Props / Attributes
-
-React Props (camelCase) and Web Component attributes (dash-case) map 1:1:
-
-| React Prop          | Web Component Attribute | Type                                     | Default | Description                                                                              |
-| ------------------- | ----------------------- | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------------- |
-| ref                 | -                       | React.Ref<EmailBuilderRef>               | -       | Ref to access component methods (getDocument, setDocument, save, getHtml, setImageUrl)   |
-| onSave              | -                       | (document: TEditorConfiguration) => void | -       | Callback when ref.save() is called                                                       |
-| onAutoSave          | -                       | (document: TEditorConfiguration) => void | -       | Callback for auto-save (2s after changes)                                                |
-| data                | data                    | TEditorConfiguration \| string           | -       | Document to load (reactive - updates when changed)                                       |
-| initialDocument     | -                       | TEditorConfiguration \| string           | -       | Initial document to load on mount (one-time only)                                        |
-| customImageProvider | -                       | React.ReactNode                          | -       | Custom image selector component to integrate your own image gallery                      |
-| mergeTags           | -                       | MergeTag[] \| MergeTagGroup              | -       | Custom merge tags to show in the text editor                                             |
-| primaryColor        | primary-color           | string                                   | #058705 | Primary theme color                                                                      |
-| secondaryColor      | secondary-color         | string                                   | #079707 | Secondary theme color                                                                    |
-| darkMode            | dark-mode               | boolean                                  | false   | Enable dark mode                                                                         |
-| height              | height                  | string                                   | -       | Container height (e.g. "calc(100vh - 80px)")                                             |
-| stickyHeader        | sticky-header           | boolean                                  | true    | Sticky header behavior                                                                   |
-| sticky              | sticky                  | boolean                                  | false   | Sticky content behavior                                                                  |
-| galleryImages       | gallery-images          | boolean                                  | false   | Enable image gallery                                                                     |
-| locale              | locale                  | string                                   | -       | UI language (en, es, it, en-US, es-419, it-IT). Falls back to dataLocale if not provided |
-| dataLocale          | data-locale             | string                                   | -       | Alternative locale prop (used as fallback if locale is not provided)                     |
-| htmlTab             | html-tab                | boolean                                  | true    | Show HTML tab                                                                            |
-| jsonTab             | json-tab                | boolean                                  | true    | Show JSON tab                                                                            |
-| imagePlaceholder    | image-placeholder       | string                                   | -       | Default placeholder for images                                                           |
-| enableAI            | enable-ai               | boolean                                  | false   | Enable AI features for text and image generation                                         |
-| onAIRequest         | -                       | (request: AIFeatureRequest) => Promise\<string\> | -  | Callback for AI text processing requests                                                 |
-| freeMode            | free-mode               | boolean                                  | true    | Enable free editing mode                                                                 |
-| showVersion         | show-version            | boolean                                  | -       | Show version indicator in the editor                                                     |
-| componentTree       | component-tree          | boolean                                  | true    | Show the component tree panel                                                            |
-
-## Internationalization (i18n)
-
-The builder supports multiple languages. Pass the `locale` prop with one of the supported values:
-
-- `en` or `en-US` - English (default)
-- `es` or `es-419` - Spanish
-- `it` or `it-IT` - Italian
-
-```tsx
-<EmailBuilder locale="es" />
-```
-
-## TypeScript
-
-Types are shipped. You can import them as:
-
-```ts
-import type { EmailBuilderProps, AIFeatureRequest, MergeTag, MergeTagGroup, EmailBuilderRef } from 'email-builder-online';
-```
-
-The `AIFeatureRequest` interface:
-
-```ts
-interface AIFeatureRequest {
-  text: string;      // Selected or relevant text
-  content: string;   // Full block content
-  action: string;    // AI action (rewrite, grammar_check, continue_writing, shorter, descriptive, detailed, friendly, professional)
-  blockId?: string;  // Block ID where the request originated
-}
-```
-
-## License
-
-MIT © Laravel42
-
-## Links
-
-- 🌐 **Website:** [laravel42.com](https://laravel42.com/)
-- 📦 **More Open Source:** [npmjs.com/~laravel42](https://www.npmjs.com/~laravel42)
-- 💼 **LinkedIn:** [Laravel42](https://www.linkedin.com/company/laravel42/)
-- 📘 **Facebook:** [Laravel42](https://www.facebook.com/Laravel42)
-- 📸 **Instagram:** [@laravel42\_](https://www.instagram.com/laravel42_/)
-
-## Changelog
-
-See Git history for details. Please open issues or PRs for bugs and improvements.
+# email-builder-online
+
+Powerful, modern email builder with drag-and-drop blocks, live preview, and HTML export. Built with React and Material UI, distributed as a React component and as a Web Component so it can be embedded in other frameworks (Nuxt 3, Next.js, SvelteKit, etc.). Compatible with React 18 and 19.
+
+🚀 **[Live Demo](https://emailbuilder.online/)**
+
+## Features
+
+- **Drag-and-drop blocks**: Text (Rich Text Editor), Image, Button, Columns, Divider, Spacer, Social Media, Container
+- **Editor and Preview tabs** with responsive screen sizes (Desktop/Mobile)
+- **Undo/Redo** and keyboard shortcuts
+- **HTML export** and copy-to-clipboard helpers
+- **CSS size guard** for email client compatibility
+- **Dark mode** support
+- **AI features** for text (rewrite, grammar, continue, tone) and image generation
+- **Image gallery** integration with custom image provider support
+- **Internationalization (i18n)** with English, Spanish, and Italian support
+- **Works as React component or Web Component** - embed in any framework (Nuxt 3, Next.js, SvelteKit, Vue, etc.)
+- **Built with TypeScript** for better developer experience
+- **Responsive design** that works on mobile and desktop
+
+## Installation
+
+Install the package along with React:
+
+```bash
+npm i email-builder-online react react-dom
+# or
+yarn add email-builder-online react react-dom
+# or
+pnpm add email-builder-online react react-dom
+```
+
+> **Note:** All other dependencies (Material UI, i18n, drag-and-drop, Tiptap, etc.) are bundled with the package — no extra installs needed.
+
+> **Requirements:** This package targets **Node 24+** and **pnpm** (declared in `engines`). Node 24 + pnpm are required when building or self-hosting the builder from source.
+
+### Peer dependencies (React / React-DOM)
+
+**`react` and `react-dom` must be the same major/minor version** (e.g. both 18.x or both 19.x). Mixing versions (e.g. react@18 with react-dom@19) can cause runtime errors such as "Cannot read properties of undefined (reading 'S')".
+
+If your project uses **Vite**, add this to your `vite.config` to avoid multiple instances of React (recommended on Windows and in monorepos):
+
+```ts
+export default defineConfig({
+  resolve: {
+    dedupe: ['react', 'react-dom', 'react-dom/client'],
+  },
+  // ...
+});
+```
+
+Add the stylesheet (required):
+
+```ts
+// React / Vite / Nuxt / Next
+import 'email-builder-online/style.css';
+```
+
+## AI Features
+
+The builder supports AI-powered features for both text and image blocks, controlled by a single `enableAI` prop.
+
+### Text AI
+
+When `enableAI` is `true`, the rich text editor (NotionText) shows AI actions in the bubble menu toolbar and slash menu:
+- Rewrite, grammar check, continue writing
+- Tone adjustments: shorter, descriptive, detailed, friendly, professional
+
+Text AI uses the `onAIRequest` callback to process requests. You provide the backend integration:
+
+```tsx
+<EmailBuilder
+  enableAI={true}
+  onAIRequest={async ({ text, content, action, blockId }) => {
+    const response = await fetch('/api/ai', {
+      method: 'POST',
+      body: JSON.stringify({ text, content, action }),
+      headers: { 'Content-Type': 'application/json' },
+    });
+    const data = await response.json();
+    return data.processedContent;
+  }}
+/>
+```
+
+### Image AI Generation
+
+When `enableAI` is `true`, image blocks and background image inputs show a "Generate with AI" button that opens a dialog for prompt-based image generation.
+
+#### Events
+
+The image AI generation uses a custom event system:
+
+**`request-ai-image`** - Fired when the user submits a prompt to generate an image
+
+```tsx
+window.addEventListener('request-ai-image', (event: CustomEvent) => {
+  const prompt = event.detail; // string: the user's prompt
+
+  // Call your AI image generation API
+  const imageUrl = await generateImage(prompt);
+
+  // Respond with the generated image
+  window.dispatchEvent(
+    new CustomEvent('generated-image', {
+      detail: { url: imageUrl, success: true },
+    })
+  );
+});
+```
+
+**`store-ai-image`** - Fired when the user confirms and inserts the generated image
+
+```tsx
+window.addEventListener('store-ai-image', (event: CustomEvent) => {
+  const imageUrl = event.detail; // string: URL of the image to store
+  // Persist the image to your storage if needed
+});
+```
+
+**`generated-image`** - Dispatch this event to return the generated image to the builder
+
+```tsx
+// Success
+window.dispatchEvent(
+  new CustomEvent('generated-image', {
+    detail: { url: 'https://example.com/generated.png', success: true },
+  })
+);
+
+// Error
+window.dispatchEvent(
+  new CustomEvent('generated-image', {
+    detail: { url: null, success: false, error: { code: 500, message: 'Generation failed' } },
+  })
+);
+```
+
+### Template AI Generation (demo)
+
+The dev playground wires `onAIGenerateTemplate` to the bundled
+[`@eb/backend`](../backend) workspace package so you can try the
+end-to-end flow (prompt → SSE NDJSON stream → live preview → Apply).
+
+Run both packages in parallel from the repo root (two terminals):
+
+```bash
+# Terminal 1 — AI backend on http://localhost:3100
+cp packages/backend/.env.example packages/backend/.env
+# edit OPENAI_API_KEY inside packages/backend/.env
+pnpm dev:backend
+
+# Terminal 2 — React 19 playground on http://localhost:2501
+pnpm dev
+```
+
+The consumer code in `playground/react-19/src/App.tsx` is the minimal
+reference: a single `fetch` to `http://localhost:3100/api/generate` that
+returns the SSE response body as a `ReadableStream<string>` to the
+builder's dialog. The backend URL is hardcoded there — change the
+`AI_BACKEND_URL` constant if your backend runs elsewhere.
+
+## Custom Image Provider
+
+You can integrate your own image selector/gallery by passing a React component through the `customImageProvider` prop. This component will be rendered at the top of the image input panel, allowing users to select images from your custom source.
+
+### Events
+
+The custom image provider can listen to and dispatch the following events:
+
+#### Listening to Events
+
+**`email-builder-image-panel-opened`** - Fired when an Image block is selected/opened in the editor
+
+```tsx
+window.addEventListener('email-builder-image-panel-opened', (event: CustomEvent) => {
+  const { blockId, currentImageUrl, alt } = event.detail;
+  // You can use this to highlight the current image in your gallery
+  // or load additional data based on the current selection
+});
+```
+
+Event detail properties:
+
+- `blockId` (string): The ID of the selected image block
+- `currentImageUrl` (string | null): The URL of the currently selected image, or null if no image is set
+- `alt` (string | null): The alt text of the current image, or null if not set
+
+#### Dispatching Events
+
+**`email-builder-set-image`** - Dispatch this event to set an image in the currently selected block
+
+```tsx
+window.dispatchEvent(
+  new CustomEvent('email-builder-set-image', {
+    detail: imageUrl, // string: URL of the image to set
+  })
+);
+```
+
+### Complete Example
+
+```tsx
+import React, { useEffect, useState } from 'react';
+import { EmailBuilder } from 'email-builder-online';
+
+function MyImageGallery() {
+  const [currentImageUrl, setCurrentImageUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Listen for when the image panel opens
+    const handlePanelOpened = (event: CustomEvent) => {
+      const { currentImageUrl } = event.detail;
+      setCurrentImageUrl(currentImageUrl);
+    };
+
+    window.addEventListener('email-builder-image-panel-opened', handlePanelOpened);
+
+    return () => {
+      window.removeEventListener('email-builder-image-panel-opened', handlePanelOpened);
+    };
+  }, []);
+
+  const handleImageSelect = (imageUrl: string) => {
+    // Dispatch event to set the image
+    window.dispatchEvent(
+      new CustomEvent('email-builder-set-image', {
+        detail: imageUrl,
+      })
+    );
+  };
+
+  return (
+    <div>
+      <h4>My Custom Gallery</h4>
+      {currentImageUrl && <p style={{ fontSize: '12px', color: '#666' }}>Current: {currentImageUrl}</p>}
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '8px' }}>
+        <img
+          src="https://example.com/image1.jpg"
+          onClick={() => handleImageSelect('https://example.com/image1.jpg')}
+          style={{
+            cursor: 'pointer',
+            width: '100%',
+            border: currentImageUrl === 'https://example.com/image1.jpg' ? '2px solid blue' : 'none',
+          }}
+        />
+        {/* More images... */}
+      </div>
+    </div>
+  );
+}
+
+export default function Page() {
+  return (
+    <EmailBuilder
+      customImageProvider={<MyImageGallery />}
+      // ... other props
+    />
+  );
+}
+```
+
+> **Live Example**: Check out the working implementation in `packages/email-builder-online/src/components/SampleImageGallery.tsx` and see it in action in the demo app.
+
+## Custom Merge Tags
+
+You can provide your own merge tags that will appear in the text editor's merge tag menu. Pass an array of tags or a complete group configuration:
+
+### Simple Array of Tags
+
+```tsx
+import { EmailBuilder, MergeTag } from 'email-builder-online';
+
+const myMergeTags: MergeTag[] = [
+  {
+    label: 'First Name',
+    value: '[first_name]',
+  },
+  {
+    label: 'Last Name',
+    value: '[last_name]',
+  },
+  {
+    label: 'Company',
+    value: '[company]',
+  },
+  {
+    type: 'divider', // Add a divider
+  },
+  {
+    label: 'Custom Link',
+    value: '{custom_link}Click here{/custom_link}',
+  },
+];
+
+export default function Page() {
+  return (
+    <EmailBuilder
+      mergeTags={myMergeTags}
+      // ... other props
+    />
+  );
+}
+```
+
+### Complete Group with Custom Icons
+
+```tsx
+import { EmailBuilder, MergeTagGroup } from 'email-builder-online';
+import { User, Building, Mail } from 'lucide-react'; // or any icon library
+
+const myMergeTagGroup: MergeTagGroup = {
+  label: 'My Custom Tags',
+  icon: <Mail />,
+  children: [
+    {
+      label: 'First Name',
+      value: '[first_name]',
+      icon: <User />,
+    },
+    {
+      label: 'Company Name',
+      value: '[company]',
+      icon: <Building />,
+    },
+    {
+      type: 'divider',
+    },
+    {
+      label: 'Verification Link',
+      value: '{verify}Verify Account{/verify}',
+      icon: <Mail />,
+    },
+  ],
+};
+
+export default function Page() {
+  return (
+    <EmailBuilder
+      mergeTags={myMergeTagGroup}
+      // ... other props
+    />
+  );
+}
+```
+
+## Programmatic Image Loading
+
+You can load images programmatically using the ref:
+
+```tsx
+import { useRef } from 'react';
+import { EmailBuilder, EmailBuilderRef } from 'email-builder-online';
+
+export default function Page() {
+  const emailBuilderRef = useRef<EmailBuilderRef>(null);
+
+  const handleSelectFromMyGallery = (imageUrl: string, blockId: string) => {
+    // Set image URL for a specific block
+    emailBuilderRef.current?.setImageUrl(blockId, imageUrl);
+  };
+
+  return (
+    <EmailBuilder
+      ref={emailBuilderRef}
+      customImageProvider={<MyCustomGallery onSelect={handleSelectFromMyGallery} />}
+    />
+  );
+}
+```
+
+### Using with Custom Image Provider Events
+
+You can combine the ref approach with the event system for a more robust solution:
+
+```tsx
+import { useRef, useEffect, useState } from 'react';
+import { EmailBuilder, EmailBuilderRef } from 'email-builder-online';
+
+function MyCustomGallery() {
+  const [currentBlockId, setCurrentBlockId] = useState<string | null>(null);
+  const [currentImageUrl, setCurrentImageUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    const handlePanelOpened = (event: CustomEvent) => {
+      const { blockId, currentImageUrl } = event.detail;
+      setCurrentBlockId(blockId);
+      setCurrentImageUrl(currentImageUrl);
+    };
+
+    window.addEventListener('email-builder-image-panel-opened', handlePanelOpened);
+    return () => window.removeEventListener('email-builder-image-panel-opened', handlePanelOpened);
+  }, []);
+
+  const handleImageSelect = (imageUrl: string) => {
+    // Use the event system to set the image
+    window.dispatchEvent(
+      new CustomEvent('email-builder-set-image', {
+        detail: imageUrl,
+      })
+    );
+  };
+
+  return (
+    <div>
+      <h4>Select Image</h4>
+      {currentImageUrl && <p>Current: {currentImageUrl}</p>}
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '8px' }}>
+        {/* Your image gallery */}
+      </div>
+    </div>
+  );
+}
+
+export default function Page() {
+  const emailBuilderRef = useRef<EmailBuilderRef>(null);
+
+  // Alternative: Use ref method directly
+  const handleSelectFromGallery = (imageUrl: string, blockId: string) => {
+    emailBuilderRef.current?.setImageUrl(blockId, imageUrl);
+  };
+
+  return <EmailBuilder ref={emailBuilderRef} customImageProvider={<MyCustomGallery />} />;
+}
+```
+
+## Available Blocks
+
+The email builder includes the following drag-and-drop blocks:
+
+- **Notion Text** - Rich text editor with Notion-like editing experience (Tiptap-based)
+- **Image** - Image block with link support
+- **Button** - Call-to-action button with customizable styling
+- **Columns** - Multi-column layout container
+- **Divider** - Horizontal divider/separator line
+- **Spacer** - Vertical spacing block
+- **Social Media** - Social media icons with links
+- **Container** - Container block for grouping content
+
+## Backward Compatibility
+
+The email builder automatically migrates legacy blocks when loading a document so templates created before the NotionText block was introduced still hydrate cleanly. The following retired block types are converted to **NotionText** on load:
+
+- **CustomEditor** → **NotionText** (type rename, compatible data)
+- **Html** → **NotionText** (`props.contents` wrapped into `props.html`)
+- **Heading** → **NotionText** (`props.text` wrapped into `<hN>…</hN>` in `props.html`)
+
+Other previously-supported types (`Wysiwyg`, `Text`, `Avatar`) were fully retired and are no longer migrated — old documents containing them will silently drop those blocks.
+
+## Usage
+
+There are three ways to use the builder:
+
+### 1) As a React component with Ref (recommended for programmatic control)
+
+Use a ref to control saving and access the document programmatically:
+
+```tsx
+import React, { useRef, useState, useEffect } from 'react';
+import { EmailBuilder, EmailBuilderRef, TEditorConfiguration, MergeTag } from 'email-builder-online';
+import 'email-builder-online/style.css';
+
+// Custom Image Gallery Component
+function MyImageGallery() {
+  const images = ['https://example.com/image1.jpg', 'https://example.com/image2.jpg', 'https://example.com/image3.jpg'];
+
+  const handleImageSelect = (imageUrl: string) => {
+    window.dispatchEvent(
+      new CustomEvent('email-builder-set-image', {
+        detail: imageUrl,
+      })
+    );
+  };
+
+  return (
+    <div>
+      <h4>My Custom Gallery</h4>
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '8px' }}>
+        {images.map((img, idx) => (
+          <img
+            key={idx}
+            src={img}
+            onClick={() => handleImageSelect(img)}
+            style={{ cursor: 'pointer', width: '100%', borderRadius: '4px' }}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// Custom Merge Tags
+const customMergeTags: MergeTag[] = [
+  {
+    label: 'First Name',
+    value: '[first_name]',
+  },
+  {
+    label: 'Last Name',
+    value: '[last_name]',
+  },
+  {
+    label: 'Company',
+    value: '[company]',
+  },
+  {
+    type: 'divider',
+  },
+  {
+    label: 'Verification Link',
+    value: '{verify}Verify your account{/verify}',
+  },
+];
+
+export default function Page() {
+  const emailBuilderRef = useRef<EmailBuilderRef>(null);
+  const [document, setDocument] = useState<TEditorConfiguration | null>(null);
+
+  // Load saved document on mount
+  useEffect(() => {
+    const saved = localStorage.getItem('draft');
+    if (saved) {
+      setDocument(JSON.parse(saved));
+    }
+  }, []);
+
+  const handleSave = () => {
+    if (emailBuilderRef.current) {
+      const document = emailBuilderRef.current.save();
+      // Send to your backend
+      fetch('/api/save', {
+        method: 'POST',
+        body: JSON.stringify(document),
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+  };
+
+  const handleExportHtml = () => {
+    if (emailBuilderRef.current) {
+      const html = emailBuilderRef.current.getHtml();
+      // Download HTML file or send to backend
+      const blob = new Blob([html], { type: 'text/html' });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = 'email.html';
+      a.click();
+      URL.revokeObjectURL(url);
+    }
+  };
+
+  const handleSendEmail = async () => {
+    if (emailBuilderRef.current) {
+      const html = emailBuilderRef.current.getHtml();
+      // Send email via your backend
+      await fetch('/api/send-email', {
+        method: 'POST',
+        body: JSON.stringify({ html }),
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+  };
+
+  return (
+    <div style={{ height: '100vh' }}>
+      <button onClick={handleSave}>Save</button>
+      <button onClick={handleExportHtml}>Export HTML</button>
+      <button onClick={handleSendEmail}>Send Email</button>
+      <EmailBuilder
+        ref={emailBuilderRef}
+        data={document}
+        onAutoSave={(doc) => localStorage.setItem('draft', JSON.stringify(doc))}
+        customImageProvider={<MyImageGallery />}
+        mergeTags={customMergeTags}
+        primaryColor="#0d9488"
+        secondaryColor="#0ea5a6"
+        locale="en"
+        height="calc(100vh - 80px)"
+      />
+    </div>
+  );
+}
+```
+
+**Ref Methods:**
+
+The `EmailBuilderRef` exposes the following methods:
+
+- `getDocument(): TEditorConfiguration` - Returns the current editor document
+- `setDocument(document: TEditorConfiguration): void` - Replaces the current document
+- `save(): TEditorConfiguration` - Flushes pending changes, calls `onSave` (if provided) and returns the document
+- `getHtml(): string` - Returns the rendered HTML for the current document
+- `setImageUrl(blockId: string, url: string): void` - Sets the URL of an image block with the given ID and updates the document
+
+### 2) As a React component (basic usage)
+
+```tsx
+import React from 'react';
+import { EmailBuilder } from 'email-builder-online';
+import 'email-builder-online/style.css';
+
+export default function Page() {
+  return (
+    <div style={{ height: '100vh' }}>
+      <EmailBuilder
+        primaryColor="#0d9488"
+        secondaryColor="#0ea5a6"
+        darkMode={false}
+        stickyHeader
+        locale="en"
+        height="calc(100vh - 80px)"
+      />
+    </div>
+  );
+}
+```
+
+### 3) As a Web Component (works in Nuxt 3, Vue, Svelte, plain HTML)
+
+For Web Component usage, the component auto-registers in browser environments. Here's how to use it in different frameworks:
+
+#### Nuxt 3 Example
+
+1. Register the email builder component:
+
+```ts
+// plugins/email-builder.client.ts
+import { registerEmailBuilder } from 'email-builder-online';
+import 'email-builder-online/style.css';
+
+export default defineNuxtPlugin(() => {
+  // Register the web component
+  registerEmailBuilder('email-builder');
+});
+```
+
+#### Vanilla JavaScript Example
+
+For plain HTML (no bundler, no React in the host page), use the **standalone build**.
+It bundles React + ReactDOM, renders inside a Shadow DOM, and auto-registers the
+`<email-builder>` element on load (no manual `registerEmailBuilder` call needed).
+
+> The standalone files (`dist/standalone.js`, `dist/standalone.mjs`) are produced by
+> `pnpm build:standalone` (or `pnpm build:all`). The regular `dist/index.*` build
+> externalizes React and is meant for bundler-based apps, not plain `<script>` usage.
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <link rel="stylesheet" href="path/to/email-builder-online/dist/style.css" />
+    <!-- IIFE build (no module support needed); exposes window.EmailBuilder -->
+    <script src="path/to/email-builder-online/dist/standalone.js"></script>
+  </head>
+  <body>
+    <!-- Auto-registered on load -->
+    <email-builder></email-builder>
+  </body>
+</html>
+```
+
+Or with the ES module variant:
+
+```html
+<link rel="stylesheet" href="path/to/email-builder-online/dist/style.css" />
+<script type="module" src="path/to/email-builder-online/dist/standalone.mjs"></script>
+<email-builder></email-builder>
+```
+
+Then use it anywhere in your templates (wrap in `<ClientOnly>` for Nuxt):
+
+```vue
+<template>
+  <ClientOnly>
+    <email-builder
+      primary-color="#0d9488"
+      secondary-color="#0ea5a6"
+      dark-mode="false"
+      sticky-header="true"
+      locale="en"
+      height="calc(100vh - 80px)"
+    />
+  </ClientOnly>
+</template>
+```
+
+For Vue/Nuxt, you can silence unknown element warnings by marking the tag as a custom element:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  vue: {
+    compilerOptions: {
+      isCustomElement: (tag) => tag === 'email-builder',
+    },
+  },
+  css: ['email-builder-online/style.css'],
+});
+```
+
+**Notes on SSR and dependencies:**
+
+- The Web Component wrapper is registered only on the client. Use a client-only plugin in SSR frameworks.
+- React and ReactDOM are peer dependencies for the package-based usage (React component and the `registerEmailBuilder` Web Component). Install them in your app or use a bundler that provides them. React 18 and 19 are supported. (The self-contained `standalone` build bundles its own React.)
+- i18n dependencies (`i18next`, `react-i18next`, `i18next-browser-languagedetector`) are **bundled** with the package — you do not need to install them separately.
+
+## Props / Attributes
+
+React Props (camelCase) and Web Component attributes (dash-case) map 1:1:
+
+| React Prop          | Web Component Attribute | Type                                     | Default | Description                                                                              |
+| ------------------- | ----------------------- | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------------- |
+| ref                 | -                       | React.Ref<EmailBuilderRef>               | -       | Ref to access component methods (getDocument, setDocument, save, getHtml, setImageUrl)   |
+| onSave              | -                       | (document: TEditorConfiguration) => void | -       | Callback when ref.save() is called                                                       |
+| onAutoSave          | -                       | (document: TEditorConfiguration) => void | -       | Callback for auto-save (2s after changes)                                                |
+| data                | data                    | TEditorConfiguration \| string           | -       | Document to load (reactive - updates when changed)                                       |
+| initialDocument     | -                       | TEditorConfiguration \| string           | -       | Initial document to load on mount (one-time only)                                        |
+| customImageProvider | -                       | React.ReactNode                          | -       | Custom image selector component to integrate your own image gallery                      |
+| mergeTags           | -                       | MergeTag[] \| MergeTagGroup              | -       | Custom merge tags to show in the text editor                                             |
+| primaryColor        | primary-color           | string                                   | #058705 | Primary theme color                                                                      |
+| secondaryColor      | secondary-color         | string                                   | #079707 | Secondary theme color                                                                    |
+| darkMode            | dark-mode               | boolean                                  | false   | Enable dark mode                                                                         |
+| height              | height                  | string                                   | -       | Container height (e.g. "calc(100vh - 80px)")                                             |
+| stickyHeader        | sticky-header           | boolean                                  | true    | Sticky header behavior                                                                   |
+| sticky              | sticky                  | boolean                                  | false   | Sticky content behavior                                                                  |
+| galleryImages       | gallery-images          | boolean                                  | false   | Enable image gallery                                                                     |
+| locale              | locale                  | string                                   | -       | UI language (en, es, it, en-US, es-419, it-IT). Falls back to dataLocale if not provided |
+| dataLocale          | data-locale             | string                                   | -       | Alternative locale prop (used as fallback if locale is not provided)                     |
+| htmlTab             | html-tab                | boolean                                  | true    | Show HTML tab                                                                            |
+| jsonTab             | json-tab                | boolean                                  | true    | Show JSON tab                                                                            |
+| imagePlaceholder    | image-placeholder       | string                                   | -       | Default placeholder for images                                                           |
+| imageUrlInput       | image-url-input         | boolean                                  | true    | Show the URL field in the Image block picker's Upload tab. When `false`, only the dropzone is rendered (subject to `imageUploadInput`). When both `imageUrlInput` and `imageUploadInput` are `false`, the Upload tab is hidden. |
+| imageUploadInput    | image-upload-input      | boolean                                  | true    | Show the drag & drop / file upload zone in the Image block picker's Upload tab. When `false`, only the URL field is rendered (subject to `imageUrlInput`). When both `imageUrlInput` and `imageUploadInput` are `false`, the Upload tab is hidden. |
+| backgroundUrlInput  | background-url-input    | boolean                                  | true    | Show the URL field in the Background image picker's Upload tab (Container, ColumnsContainer, EmailLayout). Same hide-on-both-false behavior as `imageUrlInput`. |
+| backgroundUploadInput | background-upload-input | boolean                                | true    | Show the drag & drop / file upload zone in the Background image picker's Upload tab. Same hide-on-both-false behavior as `imageUploadInput`. |
+| enableAI            | enable-ai               | boolean                                  | false   | Enable AI features for text and image generation                                         |
+| onAIRequest         | -                       | (request: AIFeatureRequest) => Promise\<string\> | -  | Callback for AI text processing requests                                                 |
+| onAIGenerateTemplate | -                      | (request: AIGenerateTemplateRequest, options: { signal: AbortSignal }) => Promise\<AIGenerateTemplateResponse\> | - | Callback for AI template generation (prompt → template). When undefined, the "Generate with AI" entry point is hidden |
+| unsplashEnabled     | -                       | boolean                                  | false   | Show the built-in Unsplash picker tab (requires the backend proxy)                       |
+| unsplashBackendUrl  | -                       | string                                   | -       | Override the backend URL used for Unsplash proxy calls                                    |
+| portalContainer     | -                       | HTMLElement                              | -       | Container element for MUI portals (menus, dialogs); useful when mounting inside Shadow DOM |
+| showVersion         | show-version            | boolean                                  | -       | Show version indicator in the editor                                                     |
+| componentTree       | component-tree          | boolean                                  | true    | Show the component tree panel                                                            |
+
+## Internationalization (i18n)
+
+The builder supports multiple languages. Pass the `locale` prop with one of the supported values:
+
+- `en` or `en-US` - English (default)
+- `es` or `es-419` - Spanish
+- `it` or `it-IT` - Italian
+
+```tsx
+<EmailBuilder locale="es" />
+```
+
+## TypeScript
+
+Types are shipped. You can import them as:
+
+```ts
+import type { EmailBuilderProps, AIFeatureRequest, MergeTag, MergeTagGroup, EmailBuilderRef } from 'email-builder-online';
+```
+
+The `AIFeatureRequest` interface:
+
+```ts
+interface AIFeatureRequest {
+  text: string;      // Selected or relevant text
+  content: string;   // Full block content
+  action: string;    // AI action (rewrite, grammar_check, continue_writing, shorter, descriptive, detailed, friendly, professional)
+  blockId?: string;  // Block ID where the request originated
+}
+```
+
+## License
+
+Free to use. © Laravel42. All rights reserved.
+
+## Links
+
+- 🌐 **Website:** [laravel42.com](https://laravel42.com/)
+- 📦 **More Packages:** [npmjs.com/~laravel42](https://www.npmjs.com/~laravel42)
+- 💼 **LinkedIn:** [Laravel42](https://www.linkedin.com/company/laravel42/)
+- 📘 **Facebook:** [Laravel42](https://www.facebook.com/Laravel42)
+- 📸 **Instagram:** [@laravel42\_](https://www.instagram.com/laravel42_/)
+
+## Changelog
+
+See Git history for details. Please open issues or PRs for bugs and improvements.