@pexelize/react-editor 1.0.5 → 2.0.0

package/README.md

@@ -1,127 +1,637 @@
 # @pexelize/react-editor
 
-React wrapper component for the **Pexelize Email Editor**.
+React wrapper for the [Pexelize Editor](https://pexelize.com) - a drag-and-drop email and page builder.
 
-## 🚀 Installation
+## Installation
 
 ```bash
 npm install @pexelize/react-editor
 ```
 
-## 📖 Usage
+## Quick Start
 
 ```tsx
-import { PexelizeEditor, PexelizeEditorRef } from '@pexelize/react-editor';
-import { useRef } from 'react';
+import { useRef, useState } from "react";
+import {
+  PexelizeEditor,
+  PexelizeEditorRef,
+  DesignJson,
+} from "@pexelize/react-editor";
 
 function EmailBuilder() {
   const editorRef = useRef<PexelizeEditorRef>(null);
+  const [lastSaved, setLastSaved] = useState<Date | null>(null);
 
-  const handleSave = () => {
-    editorRef.current?.saveDesign((design) => {
-      console.log('Saved:', design);
+  const handleExport = async () => {
+    const editor = editorRef.current?.editor;
+    if (!editor) return;
+
+    const { html, design } = await editor.exportHtmlAsync();
+    console.log("HTML:", html);
+  };
+
+  const handleSave = async () => {
+    const editor = editorRef.current?.editor;
+    if (!editor) return;
+
+    const design = await editor.getDesign();
+    await saveToBackend(design);
+    setLastSaved(new Date());
+  };
+
+  return (
+    <div style={{ height: "100vh", display: "flex", flexDirection: "column" }}>
+      <div style={{ padding: 16, borderBottom: "1px solid #eee" }}>
+        <button onClick={handleExport}>Export HTML</button>
+        <button onClick={handleSave}>Save</button>
+        {lastSaved && <span>Last saved: {lastSaved.toLocaleTimeString()}</span>}
+      </div>
+      <PexelizeEditor
+        ref={editorRef}
+        editorId={123}
+        apiKey="your-api-key"
+        height="100%"
+        options={{ editorMode: "email" }}
+        onReady={(editor) => {
+          console.log("Editor ready!");
+          // Load initial design if available
+          // editor.loadDesign(savedDesign);
+        }}
+        onLoad={() => console.log("Design loaded")}
+        onChange={(data) => {
+          console.log("Design changed:", data.type);
+          // Auto-save or mark as dirty
+        }}
+        onError={(error) => console.error("Editor error:", error)}
+      />
+    </div>
+  );
+}
+```
+
+## Complete Example with All Features
+
+```tsx
+import { useRef, useState, useCallback } from "react";
+import {
+  PexelizeEditor,
+  PexelizeEditorRef,
+  DesignJson,
+  MergeTag,
+} from "@pexelize/react-editor";
+
+function AdvancedEmailBuilder() {
+  const editorRef = useRef<PexelizeEditorRef>(null);
+  const [isDirty, setIsDirty] = useState(false);
+
+  // Merge tags for personalization
+  const mergeTags: MergeTag[] = [
+    { name: "First Name", value: "{{first_name}}" },
+    { name: "Last Name", value: "{{last_name}}" },
+    { name: "Company", value: "{{company}}" },
+  ];
+
+  const handleReady = useCallback((editor) => {
+    console.log("Editor initialized");
+
+    // Set merge tags
+    editor.setMergeTags(mergeTags);
+
+    // Set custom fonts
+    editor.setFonts({
+      showDefaultFonts: true,
+      customFonts: [{ label: "Brand Font", value: "BrandFont, sans-serif" }],
     });
+
+    // Load saved design or start blank
+    const savedDesign = localStorage.getItem("email-design");
+    if (savedDesign) {
+      editor.loadDesign(JSON.parse(savedDesign));
+    }
+  }, []);
+
+  const handleChange = useCallback(
+    (data: { design: DesignJson; type: string }) => {
+      setIsDirty(true);
+      // Auto-save to localStorage
+      localStorage.setItem("email-design", JSON.stringify(data.design));
+    },
+    [],
+  );
+
+  const handleExportHtml = async () => {
+    const editor = editorRef.current?.editor;
+    if (!editor) return;
+
+    const { html, design } = await editor.exportHtmlAsync();
+
+    // Download HTML file
+    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();
   };
 
-  const handleExport = () => {
-    editorRef.current?.exportHtml((data) => {
-      console.log('HTML:', data.html);
+  const handleExportImage = () => {
+    const editor = editorRef.current?.editor;
+    if (!editor) return;
+
+    editor.exportImage((data) => {
+      window.open(data.url, "_blank");
     });
   };
 
+  const handlePreview = () => {
+    const editor = editorRef.current?.editor;
+    editor?.showPreview("desktop");
+  };
+
+  const handleUndo = () => editorRef.current?.editor?.undo();
+  const handleRedo = () => editorRef.current?.editor?.redo();
+
   return (
-    <div>
-      <div style={{ marginBottom: '10px' }}>
-        <button onClick={handleSave}>Save</button>
-        <button onClick={handleExport}>Export HTML</button>
+    <div style={{ height: "100vh", display: "flex", flexDirection: "column" }}>
+      {/* Toolbar */}
+      <div
+        style={{
+          padding: 12,
+          borderBottom: "1px solid #ddd",
+          display: "flex",
+          gap: 8,
+        }}
+      >
+        <button onClick={handleUndo}>Undo</button>
+        <button onClick={handleRedo}>Redo</button>
+        <button onClick={handlePreview}>Preview</button>
+        <button onClick={handleExportHtml}>Export HTML</button>
+        <button onClick={handleExportImage}>Export Image</button>
+        {isDirty && <span style={{ color: "orange" }}>● Unsaved changes</span>}
       </div>
 
+      {/* Editor */}
       <PexelizeEditor
         ref={editorRef}
-        editorMode='email'
-        height='600px'
-        onReady={() => console.log('Editor ready!')}
-        onChange={({ design }) => console.log('Changed:', design)}
+        editorId={123}
+        apiKey="your-api-key"
+        height="100%"
+        editorMode="email"
+        options={{
+          appearance: { theme: "light" },
+          features: {
+            preview: true,
+            undoRedo: true,
+            imageEditor: true,
+          },
+        }}
+        onReady={handleReady}
+        onChange={handleChange}
+        onError={(error) => alert(`Error: ${error.message}`)}
       />
     </div>
   );
 }
+
+export default AdvancedEmailBuilder;
+```
+
+## Props
+
+| Prop          | Type                | Required | Description                                              |
+| ------------- | ------------------- | -------- | -------------------------------------------------------- |
+| `editorId`    | `number \| string`  | ✅       | Editor ID from your Pexelize dashboard                   |
+| `apiKey`      | `string`            | ✅       | API key from your Pexelize dashboard                     |
+| `templateId`  | `string`            | ❌       | Template ID for AI Copilot history                       |
+| `design`      | `DesignJson`        | ❌       | Initial design to load                                   |
+| `editorMode`  | `EditorMode`        | ❌       | `'email'` \| `'web'` \| `'popup'`                        |
+| `contentType` | `EditorContentType` | ❌       | `'page'` \| `'module'`                                   |
+| `ai`          | `AIConfig`          | ❌       | AI features configuration                                |
+| `height`      | `string \| number`  | ❌       | Editor height (default: `'600px'`)                       |
+| `options`     | `PexelizeConfig`    | ❌       | SDK configuration options                                |
+| `className`   | `string`            | ❌       | CSS class for the container                              |
+| `style`       | `CSSProperties`     | ❌       | Inline styles for the container                          |
+| `onReady`     | `(editor) => void`  | ❌       | Called when editor is ready                              |
+| `onLoad`      | `() => void`        | ❌       | Called when design is loaded                             |
+| `onChange`    | `(data) => void`    | ❌       | Called when design changes (receives `{ design, type }`) |
+| `onError`     | `(error) => void`   | ❌       | Called on initialization error                           |
+
+## SDK Methods Reference
+
+Access the SDK via `editorRef.current?.editor`:
+
+### Design Methods
+
+```tsx
+// Load/save design
+editor.loadDesign(design);
+editor.loadDesign(design, { preserveHistory: false });
+await editor.loadDesignAsync(design);
+editor.loadBlank();
+editor.saveDesign((design) => console.log(design));
+const design = await editor.getDesign();
+```
+
+### Export Methods
+
+```tsx
+// HTML export
+editor.exportHtml((data) => console.log(data.html, data.design));
+const { html, design, chunks } = await editor.exportHtmlAsync();
+
+// Plain text export
+editor.exportPlainText((data) => console.log(data.text));
+const { text, design } = await editor.exportPlainTextAsync();
+
+// Image export
+editor.exportImage((data) => console.log(data.url), { format: "png" });
+
+// PDF export
+editor.exportPdf((data) => console.log(data.url), { format: "A4" });
+
+// ZIP export
+editor.exportZip((data) => console.log(data.url));
+```
+
+### Merge Tags
+
+```tsx
+editor.setMergeTags([
+  { name: "First Name", value: "{{first_name}}" },
+  { name: "Company", value: "{{company}}" },
+]);
+const tags = await editor.getMergeTags();
+```
+
+### Design Tags
+
+```tsx
+editor.setDesignTags({ brand_color: "#007bff" });
+const tags = await editor.getDesignTags();
+```
+
+### Special Links
+
+```tsx
+editor.setSpecialLinks([{ name: "Unsubscribe", href: "{{unsubscribe_url}}" }]);
+const links = await editor.getSpecialLinks();
+```
+
+### Modules
+
+```tsx
+editor.setModules(modules);
+const modules = await editor.getModules();
+await editor.addModule(module);
+await editor.removeModule(moduleId);
+editor.updateModule(moduleId, rowData);
+const syncedIds = await editor.getSyncedModulesInDesign();
+await editor.unlinkSyncedModule(rowId);
+```
+
+### Fonts
+
+```tsx
+editor.setFonts({
+  showDefaultFonts: true,
+  customFonts: [{ label: "Custom Font", value: "CustomFont" }],
+});
+const fonts = await editor.getFonts();
+```
+
+### Body Values
+
+```tsx
+editor.setBodyValues({
+  backgroundColor: "#f5f5f5",
+  contentWidth: "600px",
+});
+const values = await editor.getBodyValues();
+```
+
+### Editor Options
+
+```tsx
+editor.setOptions({
+  display: { backgroundColor: "#f5f5f5", contentWidth: 600 },
+  links: { color: "#0066cc", underline: true },
+  buttonDefaults: { backgroundColor: "#3AAEE0" },
+  appearance: { theme: "auto", accentColor: "indigo" },
+});
+```
+
+### Tools Configuration
+
+```tsx
+editor.setToolsConfig({
+  heading: { enabled: true },
+  button: { properties: { colors: { value: { backgroundColor: "#007bff" } } } },
+});
+```
+
+### Tabs Management
+
+```tsx
+editor.updateTabs({
+  myCustomTab: { enabled: true, position: 1, icon: "star", active: true },
+});
+```
+
+### Editor Mode & Config
+
+```tsx
+editor.setEditorMode("email"); // 'email' | 'web' | 'popup' | 'document'
+editor.setEditorConfig({
+  minRows: 1,
+  maxRows: 1,
+  contentType: "module",
+  autoSelectOnDrop: true,
+});
+const config = await editor.getEditorConfig();
+```
+
+### Locale & Language
+
+```tsx
+editor.setLocale("en-US");
+editor.setCurrentLanguage("es-ES");
+editor.setLanguages([
+  { label: "English", value: "en-US", default: true },
+  { label: "Español", value: "es-ES" },
+]);
+const lang = await editor.getCurrentLanguage();
+editor.setTextDirection("rtl");
+```
+
+### Appearance
+
+```tsx
+editor.setAppearance({
+  theme: "dark",
+  panels: { tools: { position: "left" } },
+});
+```
+
+### Custom CSS/JS
+
+```tsx
+editor.setCustomCSS(["https://example.com/styles.css"]);
+editor.setCustomJS(["https://example.com/script.js"]);
+```
+
+### Preview
+
+```tsx
+editor.showPreview("desktop"); // 'desktop' | 'tablet' | 'mobile'
+editor.hidePreview();
+```
+
+### Undo/Redo
+
+```tsx
+editor.undo();
+editor.redo();
+const canUndo = await editor.canUndo();
+const canRedo = await editor.canRedo();
+```
+
+### Save
+
+```tsx
+editor.save(); // Triggers save callback
+```
+
+### Element Manipulation
+
+```tsx
+editor.execCommand({
+  action: "highlight",
+  target: { type: "row", id: "row-123" },
+});
+editor.selectElement({ type: "row", id: "row-123" });
+editor.highlightElement({ type: "content", id: "content-789" });
+editor.highlightElement(null); // Clear highlight
+editor.scrollToElement({ type: "row", id: "row-123" });
+```
+
+### Events
+
+```tsx
+const unsubscribe = editor.addEventListener("design:updated", (data) => {
+  console.log("Design changed:", data);
+});
+editor.removeEventListener("design:updated", callback);
 ```
 
-## 🔧 Props
+**Available Events:**
 
-| Prop         | Type                          | Default   | Description                    |
-| ------------ | ----------------------------- | --------- | ------------------------------ |
-| `editorMode` | `'email' \| 'web' \| 'popup'` | `'email'` | Editor mode                    |
-| `height`     | `string \| number`            | `'600px'` | Editor height                  |
-| `design`     | `DesignJson`                  | -         | Initial design to load         |
-| `mergeTags`  | `MergeTag[]`                  | -         | Merge tags for personalization |
-| `appearance` | `AppearanceConfig`            | -         | Visual customization           |
-| `onReady`    | `() => void`                  | -         | Called when editor is ready    |
-| `onChange`   | `(data) => void`              | -         | Called when design changes     |
-| `onLoad`     | `(data) => void`              | -         | Called when design is loaded   |
-| `onImage`    | `ImageUploadCallback`         | -         | Image upload handler           |
-| `onSave`     | `SaveCallback`                | -         | Save handler                   |
+- `editor:ready` - Editor initialized
+- `design:loaded` - Design loaded
+- `design:updated` - Design changed
+- `element:selected` - Element selected
+- `save` - Save triggered
+- `preview:shown` / `preview:hidden` - Preview toggled
+- `image:uploaded` / `image:error` - Image upload events
 
-## 📚 Ref Methods
+### Callbacks
 
-Access editor methods via ref:
+```tsx
+editor.registerCallback("image", (file, done) => {
+  uploadToMyServer(file).then((url) => done({ url }));
+});
+editor.registerCallback("save", (data, done) => {
+  saveToBackend(data).then(() => done({ success: true }));
+});
+editor.registerCallback("linkClick", (data, done) => {
+  done({ url: data.url, target: "_blank" });
+});
+editor.unregisterCallback("image");
+
+// Shorthand methods
+editor.onSave(callback);
+editor.offSave();
+editor.onChange(callback);
+editor.onLoad(callback);
+editor.onModuleSave(callback);
+editor.onSyncedModuleUpdate(callback);
+```
+
+### Tool Registration
 
 ```tsx
-const editorRef = useRef<PexelizeEditorRef>(null);
+await editor.registerTool({
+  id: "myCustomTool",
+  label: "My Tool",
+  baseToolType: "text",
+  icon: "star",
+  properties: { ... },
+});
+await editor.unregisterTool("myCustomTool");
+const tools = await editor.getTools();
+```
 
-// Load a design
-editorRef.current?.loadDesign(myDesign);
+### State
 
-// Load blank
-editorRef.current?.loadBlank();
+```tsx
+const state = await editor.getState();
+```
+
+### Collaboration
+
+```tsx
+editor.setCollaborationConfig({
+  enabled: true,
+  threadPreview: true,
+  user: { id: "user-123", name: "John Doe" },
+});
+```
 
-// Get design
-const design = await editorRef.current?.getDesign();
+### Utility Methods
 
-// Save design (callback)
-editorRef.current?.saveDesign((design) => console.log(design));
+```tsx
+editor.registerColumns([1, 2, 1]); // 1:2:1 layout
+editor.setColorPickerConfig({
+  colors: ["#FF0000", "#00FF00", "#0000FF"],
+  recentColors: true,
+});
+editor.setStyleGuide({
+  tools: {
+    heading: {
+      styles: {
+        h1: { label: "Heading 1", values: { fontSize: "32px" } },
+      },
+    },
+  },
+});
+```
 
-// Export HTML
-editorRef.current?.exportHtml((data) => console.log(data.html));
+### Validation & Audit
 
-// Export HTML (async)
-const { html, design } = await editorRef.current?.exportHtmlAsync();
+```tsx
+const result = await editor.validateTemplate(data, { strict: true, detailed: true });
+editor.validateTemplateCallback(data, (result) => console.log(result));
+const toolResult = await editor.validateTool(data, { toolType: "button" });
+const toolTypes = await editor.getToolTypes();
 
-// Undo/Redo
-editorRef.current?.undo();
-editorRef.current?.redo();
+editor.setValidator((info) => {
+  if (!info.html.includes("alt=")) {
+    return [{ id: "missing-alt", title: "Missing Alt Text", severity: "WARNING" }];
+  }
+  return [];
+});
+editor.setToolValidator("image", (info) => { ... });
+editor.clearValidators();
 
-// Check if ready
-const ready = editorRef.current?.isReady();
+const auditResult = await editor.audit();
 ```
 
-## 🪝 Hook: usePexelizeSDK
+### Display Conditions
+
+```tsx
+editor.setDisplayConditions({
+  enabled: true,
+  conditions: [
+    {
+      type: "Customer Segment",
+      label: "VIP Members",
+      before: '{% if customer.tier == "VIP" %}',
+      after: "{% endif %}",
+    },
+  ],
+});
+```
 
-For more control, use the hook directly:
+### Image Upload
 
 ```tsx
-import { usePexelizeSDK } from '@pexelize/react-editor';
+const result = await editor.uploadImage(file, {
+  folderId: "folder-123",
+  altText: "Description",
+  onProgress: (progress) => console.log(`${progress.percent}%`),
+});
+```
 
-function MyComponent() {
-  const { sdk, isReady, isLoading, error } = usePexelizeSDK({
-    containerId: 'my-editor',
-    editorMode: 'email',
-  });
+### Asset Management
 
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error}</div>;
+```tsx
+const { assets, total } = await editor.listAssets({
+  folderId: "folder-123",
+  page: 1,
+});
+const deleteResult = await editor.deleteAsset(assetId);
+const folders = await editor.listAssetFolders(parentId);
+const folder = await editor.createAssetFolder("New Folder", parentId);
+const storageInfo = await editor.getStorageInfo();
+```
+
+### AI Image
+
+```tsx
+const result = await editor.saveAiImage(base64Data, {
+  prompt: "A sunset over mountains",
+  style: "realism",
+  suggestedFilename: "ai-sunset.png",
+});
+```
+
+### Storage & AI Utilities
+
+```tsx
+editor.isExternalStorage();
+editor.canSaveAiImages();
+editor.getAssetStorageMode(); // 'pexelize' | 'external'
+editor.isAIDisabled();
+editor.isAIFeatureEnabledCheck("copilot");
+editor.isAIFeatureExternalCheck("imageGeneration");
+editor.getAIFeatureModeCheck("smartHeading"); // 'pexelize' | 'external' | 'disabled'
+editor.getAIMode();
+```
+
+### Status
+
+```tsx
+editor.isInitialized();
+editor.isReady();
+editor.destroy();
+```
+
+## Hook API
+
+```tsx
+import { PexelizeEditor, usePexelizeEditor } from "@pexelize/react-editor";
+
+function MyEditor() {
+  const { ref, editor, isReady, isLoading, error } = usePexelizeEditor();
 
   return (
     <div>
-      <div id='my-editor' style={{ height: '600px' }} />
       <button
+        onClick={() => editor?.exportHtml(console.log)}
         disabled={!isReady}
-        onClick={() => sdk?.exportHtml((d) => console.log(d.html))}
       >
         Export
       </button>
+      <PexelizeEditor ref={ref} editorId={123} apiKey="your-api-key" />
     </div>
   );
 }
 ```
+
+## TypeScript
+
+All SDK types are re-exported:
+
+```tsx
+import type {
+  PexelizeConfig,
+  DesignJson,
+  ExportHtmlData,
+  MergeTag,
+  EditorEventName,
+  AIConfig,
+} from "@pexelize/react-editor";
+```
+
+## License
+
+MIT