@savvycal/mjml-editor 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,191 @@
+# MJML Visual Email Editor
+
+A React-based visual editor for MJML email templates. Built for embedding in applications that need a user-friendly way to edit email templates while keeping MJML markup as the source of truth.
+
+## Features
+
+- **Block-based editing** - Visual representation of MJML structure with sections, columns, and content blocks
+- **Live preview** - Side-by-side HTML preview rendered in real-time
+- **Property inspector** - Edit block attributes through a settings panel
+- **Drag and drop** - Reorder blocks within columns
+- **Undo/redo** - Full history support with keyboard shortcuts
+- **MJML in, MJML out** - Takes MJML markup as input, returns modified MJML on change
+- **Liquid template support** - Autocomplete for Liquid variables and tags
+- **Theme support** - Light, dark, and system theme modes
+
+## Supported Components
+
+| Component | Description |
+|-----------|-------------|
+| `mj-section` | Row containers with background color/image |
+| `mj-column` | Responsive columns within sections |
+| `mj-text` | Text content with typography settings |
+| `mj-image` | Images with dimensions, alt text, and links |
+| `mj-button` | Call-to-action buttons with styling |
+| `mj-divider` | Horizontal separators |
+| `mj-spacer` | Vertical spacing |
+
+## Installation
+
+```bash
+npm install @savvycal/mjml-editor
+# or
+pnpm add @savvycal/mjml-editor
+```
+
+### Peer Dependencies
+
+This library requires React 18+ and Tailwind CSS v4:
+
+```bash
+npm install react react-dom tailwindcss @tailwindcss/vite tw-animate-css
+```
+
+### Styles
+
+This library is designed to work with Tailwind CSS v4. Instead of bundling all styles, the library exports CSS files that integrate with your app's Tailwind build, ensuring no style conflicts and minimal CSS overhead.
+
+Add the following imports to your app's main CSS file:
+
+```css
+@import "@savvycal/mjml-editor/preset.css";
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@savvycal/mjml-editor/components.css";
+```
+
+**Note:** `preset.css` must come before `tailwindcss` so that `@theme` tokens are registered before Tailwind generates its utilities.
+
+The `preset.css` file includes:
+- `@source` directive that tells Tailwind to scan the library's dist files for utility classes (works with npm, yarn, and pnpm)
+- `@theme` tokens that map CSS variables to Tailwind utilities
+- Custom utilities (`bg-checkered`, `shadow-framer`, etc.)
+
+The `components.css` file includes:
+- Scoped CSS variables for the editor theme (light/dark mode)
+- Tiptap/ProseMirror editor styles
+
+## Usage
+
+```tsx
+import { useState } from 'react';
+import { MjmlEditor } from '@savvycal/mjml-editor';
+
+function App() {
+  const [mjml, setMjml] = useState(initialMjml);
+
+  return (
+    <MjmlEditor
+      value={mjml}
+      onChange={setMjml}
+    />
+  );
+}
+```
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `string` | MJML markup string (required) |
+| `onChange` | `(mjml: string) => void` | Called when the document changes (required) |
+| `className` | `string` | Optional CSS class for the container |
+| `defaultTheme` | `'light' \| 'dark' \| 'system'` | Theme preference (default: `'system'`) |
+| `liquidSchema` | `LiquidSchema` | Optional schema for Liquid template autocomplete |
+| `applyThemeToDocument` | `boolean` | Whether to apply theme class to `document.documentElement`. Needed for dropdown/popover theming. Set to `false` if your app manages document-level theme classes. (default: `true`) |
+
+## Liquid Template Support
+
+The editor provides autocomplete for Liquid template variables and tags. Pass a `liquidSchema` prop to enable this feature:
+
+```tsx
+import { MjmlEditor, type LiquidSchema } from '@savvycal/mjml-editor';
+
+const liquidSchema: LiquidSchema = {
+  variables: [
+    { name: 'user.name', description: 'Recipient name' },
+    { name: 'user.email', description: 'Recipient email' },
+    { name: 'company.name', description: 'Company name' },
+  ],
+  tags: [
+    { name: 'if', description: 'Conditional block' },
+    { name: 'for', description: 'Loop block' },
+    { name: 'unless', description: 'Negative conditional' },
+  ],
+};
+
+function App() {
+  const [mjml, setMjml] = useState(initialMjml);
+
+  return (
+    <MjmlEditor
+      value={mjml}
+      onChange={setMjml}
+      liquidSchema={liquidSchema}
+    />
+  );
+}
+```
+
+When editing text content, typing `{{` will trigger variable autocomplete and `{%` will trigger tag autocomplete.
+
+## Exported Types
+
+The library exports TypeScript types for integration:
+
+```tsx
+import type {
+  MjmlNode,          // MJML document node structure
+  MjmlTagName,       // Union of supported MJML tag names
+  ContentBlockType,  // Union of content block types
+  LiquidSchema,      // Schema for Liquid autocomplete
+  LiquidSchemaItem,  // Individual variable/tag definition
+} from '@savvycal/mjml-editor';
+```
+
+### LiquidSchema
+
+```typescript
+interface LiquidSchemaItem {
+  name: string;         // Variable or tag name (e.g., "user.name")
+  description?: string; // Description shown in autocomplete
+}
+
+interface LiquidSchema {
+  variables: LiquidSchemaItem[]; // {{ variable }} syntax
+  tags: LiquidSchemaItem[];      // {% tag %} syntax
+}
+```
+
+## Theme Utilities
+
+The library exports theme utilities if you need to integrate with or control the theme externally:
+
+```tsx
+import { ThemeProvider, useTheme, ThemeToggle } from '@savvycal/mjml-editor';
+```
+
+| Export | Description |
+|--------|-------------|
+| `ThemeProvider` | Context provider for theme management |
+| `useTheme()` | Hook returning `{ theme, setTheme }` |
+| `ThemeToggle` | Pre-built UI component for theme switching |
+
+Note: `MjmlEditor` includes its own `ThemeProvider`, so you don't need to wrap it. These exports are for advanced use cases where you need theme access outside the editor.
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Cmd/Ctrl + Z` | Undo |
+| `Cmd/Ctrl + Shift + Z` | Redo |
+| `Delete` / `Backspace` | Delete selected block |
+| `Escape` | Deselect block |
+
+## Contributing
+
+See [DEVELOPING.md](../../DEVELOPING.md) for development setup and release instructions.
+
+## License
+
+MIT

package/dist/components/editor/BlockIcon.d.ts

@@ -0,0 +1,7 @@
+interface BlockIconProps {
+    type: string;
+    className?: string;
+}
+export declare function BlockIcon({ type, className }: BlockIconProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=BlockIcon.d.ts.map

package/dist/components/editor/BlockIcon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockIcon.d.ts","sourceRoot":"","sources":["../../../src/components/editor/BlockIcon.tsx"],"names":[],"mappings":"AAWA,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,SAAS,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,cAAc,2CAmB5D"}

package/dist/components/editor/BlockInspector.d.ts

@@ -0,0 +1,6 @@
+interface BlockInspectorProps {
+    onTogglePanel?: () => void;
+}
+export declare function BlockInspector({ onTogglePanel }: BlockInspectorProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=BlockInspector.d.ts.map

package/dist/components/editor/BlockInspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockInspector.d.ts","sourceRoot":"","sources":["../../../src/components/editor/BlockInspector.tsx"],"names":[],"mappings":"AA8HA,UAAU,mBAAmB;IAC3B,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,wBAAgB,cAAc,CAAC,EAAE,aAAa,EAAE,EAAE,mBAAmB,2CAuHpE"}

package/dist/components/editor/BlockInspector.js

@@ -0,0 +1,380 @@
+import { jsxs as a, jsx as e } from "react/jsx-runtime";
+import { useState as F } from "react";
+import { PanelRightClose as v, X as O, ChevronRight as _ } from "lucide-react";
+import { useEditor as N } from "../../context/EditorContext.js";
+import { ScrollArea as G } from "../ui/scroll-area.js";
+import { Button as C } from "../ui/button.js";
+import { Label as x } from "../ui/label.js";
+import { Input as b } from "../ui/input.js";
+import { Badge as I } from "../ui/badge.js";
+import { Collapsible as R, CollapsibleTrigger as L, CollapsibleContent as V } from "../ui/collapsible.js";
+import { Select as y, SelectTrigger as j, SelectValue as w, SelectContent as S, SelectItem as A } from "../ui/select.js";
+import { getSchemaForTag as z } from "../../lib/mjml/schema.js";
+import { parseClassNames as E, removeClassFromNode as B, addClassToNode as K } from "../../lib/mjml/attributes.js";
+import { cn as U } from "../../lib/utils.js";
+const P = {
+  primary: "Primary",
+  background: "Background",
+  typography: "Typography",
+  border: "Border",
+  inner: "Inner Styling",
+  sizing: "Sizing",
+  spacing: "Spacing",
+  link: "Link",
+  advanced: "Advanced"
+}, T = [
+  "primary",
+  "background",
+  "typography",
+  "border",
+  "inner",
+  "sizing",
+  "spacing",
+  "link",
+  "advanced"
+];
+function $({ node: n }) {
+  const { definedClasses: r, updateAttributes: i } = N(), d = E(n.attributes["mj-class"]);
+  if (r.length === 0)
+    return null;
+  const u = r.filter(
+    (t) => !d.includes(t)
+  ), l = (t) => {
+    if (!n._id || !t) return;
+    const o = K(n, t);
+    i(n._id, { "mj-class": o["mj-class"] || "" });
+  }, c = (t) => {
+    if (!n._id) return;
+    const o = B(n, t);
+    i(n._id, {
+      "mj-class": o["mj-class"] || ""
+    });
+  };
+  return /* @__PURE__ */ a("div", { className: "space-y-2 pb-4 mb-4 border-b border-border", children: [
+    /* @__PURE__ */ e(x, { className: "text-xs font-medium text-foreground-muted", children: "Classes" }),
+    d.length > 0 && /* @__PURE__ */ e("div", { className: "flex flex-wrap gap-1", children: d.map((t) => /* @__PURE__ */ a(
+      I,
+      {
+        variant: "secondary",
+        className: "text-xs gap-1 pr-1",
+        children: [
+          t,
+          /* @__PURE__ */ e(
+            "button",
+            {
+              type: "button",
+              onClick: () => c(t),
+              className: "ml-1 hover:text-destructive transition-colors",
+              children: /* @__PURE__ */ e(O, { className: "h-3 w-3" })
+            }
+          )
+        ]
+      },
+      t
+    )) }),
+    u.length > 0 && /* @__PURE__ */ a(y, { onValueChange: l, value: "", children: [
+      /* @__PURE__ */ e(j, { className: "h-8 text-xs border-border-subtle", children: /* @__PURE__ */ e(w, { placeholder: "Add class..." }) }),
+      /* @__PURE__ */ e(S, { children: u.map((t) => /* @__PURE__ */ e(A, { value: t, className: "text-xs", children: t }, t)) })
+    ] })
+  ] });
+}
+function le({ onTogglePanel: n }) {
+  const { selectedBlock: r, updateAttributes: i, getInheritedValue: d, definedClasses: u } = N();
+  if (!r)
+    return /* @__PURE__ */ a("div", { className: "flex flex-col h-full", children: [
+      /* @__PURE__ */ e("div", { className: "h-11 px-4 flex items-center justify-between border-b border-border bg-inspector-header", children: /* @__PURE__ */ a("div", { className: "flex items-center gap-2", children: [
+        n && /* @__PURE__ */ e(
+          C,
+          {
+            variant: "ghost",
+            size: "icon-sm",
+            onClick: n,
+            className: "h-7 w-7 rounded-md text-foreground-muted hover:text-foreground hover:bg-accent",
+            title: "Collapse panel",
+            children: /* @__PURE__ */ e(v, { className: "h-4 w-4" })
+          }
+        ),
+        /* @__PURE__ */ e("h3", { className: "text-sm font-semibold text-foreground", children: "Inspector" })
+      ] }) }),
+      /* @__PURE__ */ e("div", { className: "flex-1 flex items-center justify-center p-6", children: /* @__PURE__ */ a("p", { className: "text-sm text-foreground-muted text-center leading-relaxed", children: [
+        "Select a block to",
+        /* @__PURE__ */ e("br", {}),
+        "edit its properties"
+      ] }) })
+    ] });
+  const l = z(r.tagName), c = r.tagName.replace("mj-", "").charAt(0).toUpperCase() + r.tagName.replace("mj-", "").slice(1), t = (s, p) => {
+    r._id && i(r._id, { [s]: p });
+  }, o = l ? Object.entries(l).reduce(
+    (s, [p, h]) => {
+      const f = h.group || "primary";
+      return s[f] || (s[f] = []), s[f].push({ key: p, schema: h }), s;
+    },
+    {}
+  ) : {}, m = Object.keys(o).some(
+    (s) => s !== "primary"
+  );
+  return /* @__PURE__ */ a("div", { className: "flex flex-col h-full", children: [
+    /* @__PURE__ */ e("div", { className: "h-11 px-4 flex items-center justify-between border-b border-border bg-inspector-header", children: /* @__PURE__ */ a("div", { className: "flex items-center gap-2", children: [
+      n && /* @__PURE__ */ e(
+        C,
+        {
+          variant: "ghost",
+          size: "icon-sm",
+          onClick: n,
+          className: "h-7 w-7 rounded-md text-foreground-muted hover:text-foreground hover:bg-accent",
+          title: "Collapse panel",
+          children: /* @__PURE__ */ e(v, { className: "h-4 w-4" })
+        }
+      ),
+      /* @__PURE__ */ e("h3", { className: "text-sm font-semibold text-foreground", children: c })
+    ] }) }),
+    /* @__PURE__ */ e(G, { className: "flex-1 min-h-0", children: /* @__PURE__ */ a("div", { className: "p-4", children: [
+      u.length > 0 && /* @__PURE__ */ e($, { node: r }),
+      l ? m ? /* @__PURE__ */ e(
+        D,
+        {
+          groupedAttributes: o,
+          selectedBlock: r,
+          handleAttributeChange: t
+        }
+      ) : /* @__PURE__ */ e("div", { className: "space-y-5", children: Object.entries(l).map(([s, p]) => /* @__PURE__ */ e(
+        g,
+        {
+          attributeKey: s,
+          schema: p,
+          value: r.attributes[s] || "",
+          onChange: (h) => t(s, h),
+          inheritedValue: d(r, s)
+        },
+        s
+      )) }) : /* @__PURE__ */ e("p", { className: "text-sm text-foreground-muted py-4 text-center", children: "No editable properties for this block type." })
+    ] }) })
+  ] });
+}
+function D({
+  groupedAttributes: n,
+  selectedBlock: r,
+  handleAttributeChange: i
+}) {
+  const [d, u] = F({}), { getInheritedValue: l } = N(), c = (t) => {
+    u((o) => ({ ...o, [t]: !o[t] }));
+  };
+  return /* @__PURE__ */ e("div", { className: "space-y-4", children: T.map((t) => {
+    const o = n[t];
+    if (!o || o.length === 0) return null;
+    if (t === "primary")
+      return /* @__PURE__ */ e("div", { className: "space-y-5", children: o.map(({ key: s, schema: p }) => /* @__PURE__ */ e(
+        g,
+        {
+          attributeKey: s,
+          schema: p,
+          value: r.attributes[s] || "",
+          onChange: (h) => i(s, h),
+          inheritedValue: l(r, s)
+        },
+        s
+      )) }, t);
+    const m = d[t] || !1;
+    return /* @__PURE__ */ a(
+      R,
+      {
+        open: m,
+        onOpenChange: () => c(t),
+        children: [
+          /* @__PURE__ */ a(L, { className: "flex items-center gap-1 w-full py-2 text-xs font-medium text-foreground-muted hover:text-foreground transition-colors", children: [
+            /* @__PURE__ */ e(
+              _,
+              {
+                className: U(
+                  "h-3.5 w-3.5 transition-transform",
+                  m && "rotate-90"
+                )
+              }
+            ),
+            P[t]
+          ] }),
+          /* @__PURE__ */ e(V, { children: /* @__PURE__ */ e("div", { className: "space-y-5 pt-2 pb-1", children: o.map(({ key: s, schema: p }) => /* @__PURE__ */ e(
+            g,
+            {
+              attributeKey: s,
+              schema: p,
+              value: r.attributes[s] || "",
+              onChange: (h) => i(s, h),
+              inheritedValue: l(r, s)
+            },
+            s
+          )) }) })
+        ]
+      },
+      t
+    );
+  }) });
+}
+function g({
+  attributeKey: n,
+  schema: r,
+  value: i,
+  onChange: d,
+  inheritedValue: u
+}) {
+  const l = `attr-${n}`, c = u || r.placeholder || r.default || "";
+  switch (r.type) {
+    case "select": {
+      const t = i || u || r.default || r.options?.[0]?.value || "default", o = (m) => {
+        d(m === "false" ? "" : m);
+      };
+      return /* @__PURE__ */ a("div", { className: "space-y-2", children: [
+        /* @__PURE__ */ e(
+          x,
+          {
+            htmlFor: l,
+            className: "text-xs font-medium text-foreground-muted",
+            children: r.label
+          }
+        ),
+        /* @__PURE__ */ a(y, { value: t, onValueChange: o, children: [
+          /* @__PURE__ */ e(j, { id: l, className: "h-8 text-xs border-border-subtle", children: /* @__PURE__ */ e(
+            w,
+            {
+              placeholder: `Select ${r.label.toLowerCase()}`
+            }
+          ) }),
+          /* @__PURE__ */ e(S, { children: r.options?.map((m) => /* @__PURE__ */ e(
+            A,
+            {
+              value: m.value,
+              className: "text-xs",
+              children: m.label
+            },
+            m.value
+          )) })
+        ] })
+      ] });
+    }
+    case "color":
+      return /* @__PURE__ */ a("div", { className: "space-y-2", children: [
+        /* @__PURE__ */ e(
+          x,
+          {
+            htmlFor: l,
+            className: "text-xs font-medium text-foreground-muted",
+            children: r.label
+          }
+        ),
+        /* @__PURE__ */ a("div", { className: "flex gap-2", children: [
+          /* @__PURE__ */ e(
+            b,
+            {
+              id: l,
+              type: "color",
+              value: i || u || r.default || "#000000",
+              onChange: (t) => d(t.target.value),
+              className: "h-8 w-10 p-0.5 cursor-pointer rounded-md border-border-subtle"
+            }
+          ),
+          /* @__PURE__ */ e(
+            b,
+            {
+              type: "text",
+              value: i || "",
+              onChange: (t) => d(t.target.value),
+              placeholder: c || "#000000",
+              className: "h-8 text-xs flex-1 font-mono border-border-subtle"
+            }
+          )
+        ] })
+      ] });
+    case "padding":
+      return /* @__PURE__ */ a("div", { className: "space-y-2", children: [
+        /* @__PURE__ */ e(
+          x,
+          {
+            htmlFor: l,
+            className: "text-xs font-medium text-foreground-muted",
+            children: r.label
+          }
+        ),
+        /* @__PURE__ */ e(
+          b,
+          {
+            id: l,
+            type: "text",
+            value: i || "",
+            onChange: (t) => d(t.target.value),
+            placeholder: c || "10px 25px",
+            className: "h-8 text-xs border-border-subtle"
+          }
+        ),
+        /* @__PURE__ */ e("p", { className: "text-[10px] text-foreground-subtle", children: "Format: top right bottom left (e.g., 10px 20px)" })
+      ] });
+    case "dimension":
+      return /* @__PURE__ */ a("div", { className: "space-y-2", children: [
+        /* @__PURE__ */ e(
+          x,
+          {
+            htmlFor: l,
+            className: "text-xs font-medium text-foreground-muted",
+            children: r.label
+          }
+        ),
+        /* @__PURE__ */ e(
+          b,
+          {
+            id: l,
+            type: "text",
+            value: i || "",
+            onChange: (t) => d(t.target.value),
+            placeholder: c,
+            className: "h-8 text-xs border-border-subtle"
+          }
+        )
+      ] });
+    case "url":
+      return /* @__PURE__ */ a("div", { className: "space-y-2", children: [
+        /* @__PURE__ */ e(
+          x,
+          {
+            htmlFor: l,
+            className: "text-xs font-medium text-foreground-muted",
+            children: r.label
+          }
+        ),
+        /* @__PURE__ */ e(
+          b,
+          {
+            id: l,
+            type: "url",
+            value: i || "",
+            onChange: (t) => d(t.target.value),
+            placeholder: c || "https://...",
+            className: "h-8 text-xs border-border-subtle"
+          }
+        )
+      ] });
+    default:
+      return /* @__PURE__ */ a("div", { className: "space-y-2", children: [
+        /* @__PURE__ */ e(
+          x,
+          {
+            htmlFor: l,
+            className: "text-xs font-medium text-foreground-muted",
+            children: r.label
+          }
+        ),
+        /* @__PURE__ */ e(
+          b,
+          {
+            id: l,
+            type: "text",
+            value: i || "",
+            onChange: (t) => d(t.target.value),
+            placeholder: c,
+            className: "h-8 text-xs border-border-subtle"
+          }
+        )
+      ] });
+  }
+}
+export {
+  le as BlockInspector
+};

package/dist/components/editor/EditorCanvas.d.ts

@@ -0,0 +1,11 @@
+export type PreviewMode = 'desktop' | 'mobile';
+export type EditorTabType = 'edit' | 'preview' | 'source';
+interface EditorCanvasProps {
+    activeTab: EditorTabType;
+    onTabChange: (tab: EditorTabType) => void;
+    leftPanelOpen?: boolean;
+    rightPanelOpen?: boolean;
+}
+export declare function EditorCanvas({ activeTab, onTabChange, leftPanelOpen, rightPanelOpen, }: EditorCanvasProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=EditorCanvas.d.ts.map

package/dist/components/editor/EditorCanvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EditorCanvas.d.ts","sourceRoot":"","sources":["../../../src/components/editor/EditorCanvas.tsx"],"names":[],"mappings":"AAWA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE/C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE1D,UAAU,iBAAiB;IACzB,SAAS,EAAE,aAAa,CAAC;IACzB,WAAW,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,CAAC;IAC1C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,YAAY,CAAC,EAC3B,SAAS,EACT,WAAW,EACX,aAAa,EACb,cAAc,GACf,EAAE,iBAAiB,2CA0GnB"}