@marlinjai/email-editor 0.2.0 → 0.3.0

package/dist/react.d.mts

@@ -1,10 +1,57 @@
 import * as react from 'react';
-import { TemplateSnapshotIn, TemplateSnapshotOut, BlockDefinition } from '@marlinjai/email-editor-core';
+import { CSSProperties } from 'react';
+import { TemplateSnapshotOut, TemplateSnapshotIn, BlockDefinition } from '@marlinjai/email-editor-core';
 export { BlockDefinition, TemplateSnapshotIn, TemplateSnapshotOut } from '@marlinjai/email-editor-core';
 import { OnRequestImage, OnSaveSection } from '@marlinjai/email-editor-ui';
 export { ImageRequest, OnRequestImage, OnSaveSection, RequestedImage } from '@marlinjai/email-editor-ui';
 import { b as EditorTheme, S as SavedSectionInput } from './types-G7Ak2dWQ.mjs';
 
+/**
+ * Two things about the editor are easy to get wrong, and getting either wrong
+ * loses somebody's work silently, so they live here rather than in each screen
+ * that embeds the editor:
+ *
+ * 1. **The editor reports a snapshot on mount.** It normalises what it was
+ *    given, and says so. That first report is the baseline, not an edit: a
+ *    screen that treated it as one would show "unsaved changes" on every open
+ *    and would ask before leaving a document nobody touched. `touched` is set
+ *    by a real interaction (a pointer or a key inside the editor), and only
+ *    then does a report mean a change.
+ *
+ * 2. **The editor reports changes debounced.** The document it last reported
+ *    may be one edit behind, so reading it the moment somebody presses Save
+ *    would store the previous document and drop the edit just made. `settled()`
+ *    waits out that window since the last interaction before reading.
+ */
+/** The store's own `onChange` debounce, plus a little room. */
+declare const EDITOR_CHANGE_DEBOUNCE_MS = 300;
+/** The document as a service stores it: the editor's snapshot without its local id. */
+declare function toStoredDocument(snapshot: TemplateSnapshotOut | Record<string, unknown>): Record<string, unknown>;
+type EditorDocument = {
+    /** Whether the person has changed anything since the last save. */
+    dirty: boolean;
+    setDirty: (dirty: boolean) => void;
+    /** Hand to the editor's `onChange`. */
+    onChange: (snapshot: TemplateSnapshotOut) => void;
+    /** Hand to the host element's `onPointerDownCapture` and `onKeyDownCapture`. */
+    interacted: () => void;
+    /** The current document, once the editor's debounce window has passed. */
+    settled: () => Promise<Record<string, unknown>>;
+    /** Replaces what is held, for a document loaded or rewritten from outside the editor. */
+    replace: (document: Record<string, unknown>, opts?: {
+        touched?: boolean;
+    }) => void;
+    /** What is held right now, without waiting. Prefer `settled()` before storing it. */
+    current: () => Record<string, unknown>;
+};
+declare function useEditorDocument(initial: Record<string, unknown>): EditorDocument;
+
+/**
+ * CSS custom properties for the editor's root element. Returns an empty
+ * object when there is no theme, so the stylesheet defaults apply.
+ */
+declare function themeToStyle(theme: EditorTheme | undefined): CSSProperties;
+
 interface EmailEditorReactProps {
     /** Initial template data (uncontrolled) */
     initialTemplate?: TemplateSnapshotIn;
@@ -48,4 +95,4 @@ interface EmailEditorReactProps {
  */
 declare function EmailEditorReact({ initialTemplate, onChange, theme, blocks, onSave, onExport, onNavigateBack, onRequestImage, savedSections, onSaveSection, builtInSections, placeholderBase, }: EmailEditorReactProps): react.JSX.Element;
 
-export { EditorTheme, EmailEditorReact, SavedSectionInput };
+export { EDITOR_CHANGE_DEBOUNCE_MS, type EditorDocument, EditorTheme, EmailEditorReact, type EmailEditorReactProps, SavedSectionInput, themeToStyle, toStoredDocument, useEditorDocument };

package/dist/react.d.ts

@@ -1,10 +1,57 @@
 import * as react from 'react';
-import { TemplateSnapshotIn, TemplateSnapshotOut, BlockDefinition } from '@marlinjai/email-editor-core';
+import { CSSProperties } from 'react';
+import { TemplateSnapshotOut, TemplateSnapshotIn, BlockDefinition } from '@marlinjai/email-editor-core';
 export { BlockDefinition, TemplateSnapshotIn, TemplateSnapshotOut } from '@marlinjai/email-editor-core';
 import { OnRequestImage, OnSaveSection } from '@marlinjai/email-editor-ui';
 export { ImageRequest, OnRequestImage, OnSaveSection, RequestedImage } from '@marlinjai/email-editor-ui';
 import { b as EditorTheme, S as SavedSectionInput } from './types-G7Ak2dWQ.js';
 
+/**
+ * Two things about the editor are easy to get wrong, and getting either wrong
+ * loses somebody's work silently, so they live here rather than in each screen
+ * that embeds the editor:
+ *
+ * 1. **The editor reports a snapshot on mount.** It normalises what it was
+ *    given, and says so. That first report is the baseline, not an edit: a
+ *    screen that treated it as one would show "unsaved changes" on every open
+ *    and would ask before leaving a document nobody touched. `touched` is set
+ *    by a real interaction (a pointer or a key inside the editor), and only
+ *    then does a report mean a change.
+ *
+ * 2. **The editor reports changes debounced.** The document it last reported
+ *    may be one edit behind, so reading it the moment somebody presses Save
+ *    would store the previous document and drop the edit just made. `settled()`
+ *    waits out that window since the last interaction before reading.
+ */
+/** The store's own `onChange` debounce, plus a little room. */
+declare const EDITOR_CHANGE_DEBOUNCE_MS = 300;
+/** The document as a service stores it: the editor's snapshot without its local id. */
+declare function toStoredDocument(snapshot: TemplateSnapshotOut | Record<string, unknown>): Record<string, unknown>;
+type EditorDocument = {
+    /** Whether the person has changed anything since the last save. */
+    dirty: boolean;
+    setDirty: (dirty: boolean) => void;
+    /** Hand to the editor's `onChange`. */
+    onChange: (snapshot: TemplateSnapshotOut) => void;
+    /** Hand to the host element's `onPointerDownCapture` and `onKeyDownCapture`. */
+    interacted: () => void;
+    /** The current document, once the editor's debounce window has passed. */
+    settled: () => Promise<Record<string, unknown>>;
+    /** Replaces what is held, for a document loaded or rewritten from outside the editor. */
+    replace: (document: Record<string, unknown>, opts?: {
+        touched?: boolean;
+    }) => void;
+    /** What is held right now, without waiting. Prefer `settled()` before storing it. */
+    current: () => Record<string, unknown>;
+};
+declare function useEditorDocument(initial: Record<string, unknown>): EditorDocument;
+
+/**
+ * CSS custom properties for the editor's root element. Returns an empty
+ * object when there is no theme, so the stylesheet defaults apply.
+ */
+declare function themeToStyle(theme: EditorTheme | undefined): CSSProperties;
+
 interface EmailEditorReactProps {
     /** Initial template data (uncontrolled) */
     initialTemplate?: TemplateSnapshotIn;
@@ -48,4 +95,4 @@ interface EmailEditorReactProps {
  */
 declare function EmailEditorReact({ initialTemplate, onChange, theme, blocks, onSave, onExport, onNavigateBack, onRequestImage, savedSections, onSaveSection, builtInSections, placeholderBase, }: EmailEditorReactProps): react.JSX.Element;
 
-export { EditorTheme, EmailEditorReact, SavedSectionInput };
+export { EDITOR_CHANGE_DEBOUNCE_MS, type EditorDocument, EditorTheme, EmailEditorReact, type EmailEditorReactProps, SavedSectionInput, themeToStyle, toStoredDocument, useEditorDocument };

package/dist/react.js

@@ -20,11 +20,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/react.tsx
 var react_exports = {};
 __export(react_exports, {
-  EmailEditorReact: () => EmailEditorReact
+  EDITOR_CHANGE_DEBOUNCE_MS: () => EDITOR_CHANGE_DEBOUNCE_MS,
+  EmailEditorReact: () => EmailEditorReact,
+  themeToStyle: () => themeToStyle,
+  toStoredDocument: () => toStoredDocument,
+  useEditorDocument: () => useEditorDocument
 });
 module.exports = __toCommonJS(react_exports);
-var import_react = require("react");
-var import_email_editor_core2 = require("@marlinjai/email-editor-core");
+var import_react2 = require("react");
+var import_email_editor_core3 = require("@marlinjai/email-editor-core");
 var import_email_editor_blocks = require("@marlinjai/email-editor-blocks");
 var import_email_editor_ui = require("@marlinjai/email-editor-ui");
 
@@ -70,6 +74,47 @@ function assertSupportedBlocks(blocks) {
   }
 }
 
+// src/editorDocument.ts
+var import_react = require("react");
+var import_email_editor_core2 = require("@marlinjai/email-editor-core");
+var EDITOR_CHANGE_DEBOUNCE_MS = import_email_editor_core2.DEFAULT_ON_CHANGE_DEBOUNCE_MS;
+var SETTLE_MARGIN_MS = 100;
+function toStoredDocument(snapshot) {
+  const { id: _id, ...rest } = snapshot;
+  return rest;
+}
+function useEditorDocument(initial) {
+  const [dirty, setDirty] = (0, import_react.useState)(false);
+  const latest = (0, import_react.useRef)(toStoredDocument(initial));
+  const touched = (0, import_react.useRef)(false);
+  const lastInteraction = (0, import_react.useRef)(0);
+  const onChange = (0, import_react.useCallback)((snapshot) => {
+    latest.current = toStoredDocument(snapshot);
+    if (touched.current) setDirty(true);
+  }, []);
+  const interacted = (0, import_react.useCallback)(() => {
+    touched.current = true;
+    lastInteraction.current = Date.now();
+  }, []);
+  const settled = (0, import_react.useCallback)(async () => {
+    const wait = lastInteraction.current + EDITOR_CHANGE_DEBOUNCE_MS + SETTLE_MARGIN_MS - Date.now();
+    if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+    return latest.current;
+  }, []);
+  const replace = (0, import_react.useCallback)((document, opts = {}) => {
+    latest.current = toStoredDocument(document);
+    if (opts.touched) {
+      touched.current = true;
+      setDirty(true);
+    } else {
+      touched.current = false;
+      setDirty(false);
+    }
+  }, []);
+  const current = (0, import_react.useCallback)(() => latest.current, []);
+  return { dirty, setDirty, onChange, interacted, settled, replace, current };
+}
+
 // src/react.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 function EmailEditorReact({
@@ -86,7 +131,7 @@ function EmailEditorReact({
   builtInSections = true,
   placeholderBase
 }) {
-  const [registry] = (0, import_react.useState)(() => {
+  const [registry] = (0, import_react2.useState)(() => {
     assertSupportedBlocks(blocks);
     const reg = (0, import_email_editor_blocks.createStandardBlockRegistry)({ placeholderBase });
     blocks.forEach((block) => {
@@ -95,13 +140,13 @@ function EmailEditorReact({
     });
     return reg;
   });
-  const [prebuiltRegistry] = (0, import_react.useState)(() => {
-    const reg = builtInSections ? (0, import_email_editor_blocks.createStandardPrebuiltRegistry)({ placeholderBase }) : (0, import_email_editor_core2.createPrebuiltTemplateRegistry)();
+  const [prebuiltRegistry] = (0, import_react2.useState)(() => {
+    const reg = builtInSections ? (0, import_email_editor_blocks.createStandardPrebuiltRegistry)({ placeholderBase }) : (0, import_email_editor_core3.createPrebuiltTemplateRegistry)();
     registerSavedSections(reg, savedSections ?? []);
     return reg;
   });
-  const savedSectionNames = (0, import_react.useMemo)(() => (savedSections ?? []).map((s) => s.name), [savedSections]);
-  const style = (0, import_react.useMemo)(() => themeToStyle(theme), [theme]);
+  const savedSectionNames = (0, import_react2.useMemo)(() => (savedSections ?? []).map((s) => s.name), [savedSections]);
+  const style = (0, import_react2.useMemo)(() => themeToStyle(theme), [theme]);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
     import_email_editor_ui.EmailEditor,
     {
@@ -121,5 +166,9 @@ function EmailEditorReact({
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  EmailEditorReact
+  EDITOR_CHANGE_DEBOUNCE_MS,
+  EmailEditorReact,
+  themeToStyle,
+  toStoredDocument,
+  useEditorDocument
 });

package/dist/react.mjs

@@ -5,10 +5,53 @@ import {
 } from "./chunk-EFHKH3BN.mjs";
 
 // src/react.tsx
-import { useMemo, useState } from "react";
+import { useMemo, useState as useState2 } from "react";
 import { createPrebuiltTemplateRegistry } from "@marlinjai/email-editor-core";
 import { createStandardBlockRegistry, createStandardPrebuiltRegistry } from "@marlinjai/email-editor-blocks";
 import { EmailEditor } from "@marlinjai/email-editor-ui";
+
+// src/editorDocument.ts
+import { useCallback, useRef, useState } from "react";
+import { DEFAULT_ON_CHANGE_DEBOUNCE_MS } from "@marlinjai/email-editor-core";
+var EDITOR_CHANGE_DEBOUNCE_MS = DEFAULT_ON_CHANGE_DEBOUNCE_MS;
+var SETTLE_MARGIN_MS = 100;
+function toStoredDocument(snapshot) {
+  const { id: _id, ...rest } = snapshot;
+  return rest;
+}
+function useEditorDocument(initial) {
+  const [dirty, setDirty] = useState(false);
+  const latest = useRef(toStoredDocument(initial));
+  const touched = useRef(false);
+  const lastInteraction = useRef(0);
+  const onChange = useCallback((snapshot) => {
+    latest.current = toStoredDocument(snapshot);
+    if (touched.current) setDirty(true);
+  }, []);
+  const interacted = useCallback(() => {
+    touched.current = true;
+    lastInteraction.current = Date.now();
+  }, []);
+  const settled = useCallback(async () => {
+    const wait = lastInteraction.current + EDITOR_CHANGE_DEBOUNCE_MS + SETTLE_MARGIN_MS - Date.now();
+    if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+    return latest.current;
+  }, []);
+  const replace = useCallback((document, opts = {}) => {
+    latest.current = toStoredDocument(document);
+    if (opts.touched) {
+      touched.current = true;
+      setDirty(true);
+    } else {
+      touched.current = false;
+      setDirty(false);
+    }
+  }, []);
+  const current = useCallback(() => latest.current, []);
+  return { dirty, setDirty, onChange, interacted, settled, replace, current };
+}
+
+// src/react.tsx
 import { jsx } from "react/jsx-runtime";
 function EmailEditorReact({
   initialTemplate,
@@ -24,7 +67,7 @@ function EmailEditorReact({
   builtInSections = true,
   placeholderBase
 }) {
-  const [registry] = useState(() => {
+  const [registry] = useState2(() => {
     assertSupportedBlocks(blocks);
     const reg = createStandardBlockRegistry({ placeholderBase });
     blocks.forEach((block) => {
@@ -33,7 +76,7 @@ function EmailEditorReact({
     });
     return reg;
   });
-  const [prebuiltRegistry] = useState(() => {
+  const [prebuiltRegistry] = useState2(() => {
     const reg = builtInSections ? createStandardPrebuiltRegistry({ placeholderBase }) : createPrebuiltTemplateRegistry();
     registerSavedSections(reg, savedSections ?? []);
     return reg;
@@ -58,5 +101,9 @@ function EmailEditorReact({
   );
 }
 export {
-  EmailEditorReact
+  EDITOR_CHANGE_DEBOUNCE_MS,
+  EmailEditorReact,
+  themeToStyle,
+  toStoredDocument,
+  useEditorDocument
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marlinjai/email-editor",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Embeddable visual email editor (React component and vanilla factory) that produces an MJML-compilable document",
   "license": "MIT",
   "repository": {
@@ -47,9 +47,9 @@
     "./styles.css": "./dist/styles.css"
   },
   "dependencies": {
-    "@marlinjai/email-editor-blocks": "^0.2.0",
-    "@marlinjai/email-editor-ui": "^0.2.0",
-    "@marlinjai/email-editor-core": "^0.2.0"
+    "@marlinjai/email-editor-blocks": "^0.3.0",
+    "@marlinjai/email-editor-ui": "^0.3.0",
+    "@marlinjai/email-editor-core": "^0.3.0"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",