@kontakto/email-template-editor 1.5.1 → 2.0.0

package/README.md

@@ -49,14 +49,70 @@ function MyApp() {
 | `initialTemplate` | object | - | Initial template to load when editor first mounts |
 | `initialTemplateId` | string | - | ID of the initial template |
 | `initialTemplateName` | string | - | Name of the initial template |
-| `onSave` | function | - | Callback when template is saved: `(template) => void` |
+| `onSave` | function | - | Callback when template is saved: `(payload: SavePayload) => void \| Promise<void>` (see SavePayload below) |
 | `onChange` | function | - | Callback when template changes: `(template) => void` |
-| `loadSamples` | function | - | Loads sample templates: `() => Promise<SampleTemplate[]>` |
-| `loadTemplates` | function | - | Loads user templates: `() => Promise<SampleTemplate[]>` |
+| `loadSamples` | function | - | Loads sample templates: `() => Promise<TemplateListItem[]>` |
+| `loadTemplates` | function | - | Loads user templates: `() => Promise<TemplateListItem[]>` |
 | `loadTemplate` | function | - | Loads specific template: `(id) => Promise<Template>` |
 | `deleteTemplate` | function | - | Deletes a template: `(id) => void` |
 | `copyTemplate` | function | - | Copies a template: `(name, content) => void` |
-| `saveAs` | function | - | Saves template with new name: `(name, content) => Promise<{id, name}>` |
+| `renameTemplate` | function | - | Renames a template: `(id, newSlug) => void \| Promise<void>` |
+| `setTemplateKind` | function | - | Promotes/demotes a row between template and sample: `(id, kind) => void \| Promise<void>`. When omitted, promote/demote menu items are hidden. |
+| `saveAs` | function | - | Saves template with a new name: `(name, payload: SavePayload) => Promise<{ id, slug }>` |
+
+`TemplateListItem` is the lean list-endpoint shape (no `editor_config`):
+
+```ts
+type TemplateKind = 'template' | 'sample';
+
+type TemplateListItem = {
+  id: string;
+  slug: string;                 // primary label
+  kind: TemplateKind;           // 'template' (editable) or 'sample' (read-only starting point)
+  description?: string;         // secondary line
+  subject?: string;
+  variables?: Array<{ name: string; description?: string }>;
+  tags?: string[];
+  thumbnailUrl?: string;
+  createdAt?: string;
+  updatedAt?: string;
+};
+```
+
+The drawer groups rows by `kind`, not by which callback returned them. Both `loadTemplates` and `loadSamples` should return their items with the correct `kind`; backends typically scope the two endpoints differently (per-user vs. org-wide), but the `kind` field is what determines the section a row appears in.
+
+Samples are read-only starting points: Save on a loaded sample is disabled — the user must use Save As, which creates a fresh row with `kind='template'`.
+
+#### Subject and variables
+
+Email subject and template variables are stored on the `EmailLayout` block's data and round-trip with the editor configuration:
+
+```ts
+type EmailLayoutData = {
+  // ...style fields
+  subject?: string;
+  variables?: Array<{ name: string; description?: string }>;
+};
+```
+
+The editor renders a subject input above the canvas (always visible, supports `{{variable}}` syntax) and a Variables tab in the right inspector panel for declaring variables. Both persist via the standard save flow — consumers who previously stored `subject` in a separate DB column can read it from the saved `editor_config` instead.
+
+#### Save payload
+
+`onSave` and `saveAs` receive the same `SavePayload`. The editor renders body HTML and plain text on every save so consumers don't ship the renderer themselves:
+
+```ts
+type SavePayload = {
+  editorConfig: TEditorConfiguration;   // source of truth
+  subject?: string;                     // from the subject input
+  variables?: Array<{ name: string; description?: string }>;
+  bodyHtml: string;                     // pre-rendered, ready to send
+  bodyText: string;                     // pre-rendered, ready to send
+};
+```
+
+The `renderToStaticMarkup` and `renderToText` utilities are also exposed publicly for consumers that need to re-render outside the save flow (e.g. batch jobs).
+
 | `theme` | object | theme.ts | Custom theme for the EmailEditor, must be a Material UI theme object |
 
 #### Imperative API