email-builder-online 4.0.1 → 4.1.2

package/README.md

@@ -6,7 +6,7 @@ Powerful, modern email builder with drag-and-drop blocks, live preview, and HTML
 
 ## Features
 
-- **Drag-and-drop blocks**: Text (Rich Text Editor), Heading, Image, Button, Columns, Divider, Spacer, HTML, Social Media, Container
+- **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
@@ -33,6 +33,8 @@ 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')".
@@ -135,6 +137,30 @@ window.dispatchEvent(
 );
 ```
 
+### 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.
@@ -235,7 +261,7 @@ export default function Page() {
 }
 ```
 
-> **Live Example**: Check out the working implementation in `packages/editor-sample/src/components/SampleImageGallery.tsx` and see it in action in the demo app.
+> **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
 
@@ -403,29 +429,24 @@ export default function Page() {
 
 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
+- **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
-- **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:
+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 blocks** → Automatically converted to **NotionText**
-- **Wysiwyg blocks** → Automatically converted to **NotionText**
-- **Avatar blocks** → Automatically converted to **Image** (circular style maps to pill shape)
+- **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`)
 
-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.
+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
 
@@ -617,24 +638,37 @@ export default defineNuxtPlugin(() => {
 
 #### 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/style.css" />
-    <script src="path/to/email-builder-online/dist/index.umd.js"></script>
+    <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>
-    <script>
-      // Register the web component
-      window.EmailBuilder.registerEmailBuilder('email-builder');
-    </script>
-
+    <!-- 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
@@ -669,46 +703,8 @@ export default defineNuxtConfig({
 **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"
-}
-```
+- 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
 
@@ -735,9 +731,16 @@ React Props (camelCase) and Web Component attributes (dash-case) map 1:1:
 | 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                                                 |
-| freeMode            | free-mode               | boolean                                  | true    | Enable free editing mode                                                                 |
+| 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                                                            |
 
@@ -774,12 +777,12 @@ interface AIFeatureRequest {
 
 ## License
 
-MIT © Laravel42
+Free to use. © Laravel42. All rights reserved.
 
 ## Links
 
 - 🌐 **Website:** [laravel42.com](https://laravel42.com/)
-- 📦 **More Open Source:** [npmjs.com/~laravel42](https://www.npmjs.com/~laravel42)
+- 📦 **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_/)