@kontakto/email-template-editor 2.0.0 → 2.2.0

package/README.md

@@ -59,6 +59,9 @@ function MyApp() {
 | `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 }>` |
+| `uploadImage` | function | - | Uploads a single image file: `(file: File) => Promise<UploadedImage>`. Enables the Upload button on the Image inspector, drag-and-drop on the canvas, and paste-image-to-insert. When omitted, all upload UI is hidden and URL paste remains the only way to set an image. |
+| `loadImages` | function | - | Lists previously uploaded images for the library picker: `() => Promise<LibraryImage[]>`. Enables the "Library" button on the Image inspector. When omitted, the library button is hidden. |
+| `deleteImage` | function | - | Deletes an image from the library by URL: `(url: string) => Promise<void>`. When omitted, the per-row delete button in the library is hidden. |
 
 `TemplateListItem` is the lean list-endpoint shape (no `editor_config`):
 
@@ -91,12 +94,19 @@ Email subject and template variables are stored on the `EmailLayout` block's dat
 type EmailLayoutData = {
   // ...style fields
   subject?: string;
-  variables?: Array<{ name: string; description?: string }>;
+  variables?: Array<{ name: string; description?: string; sampleValue?: 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.
 
+The Variables tab supports Handlebars-aware management:
+
+- **Add/rename/delete**. Names follow Handlebars identifier rules (`[A-Za-z_][A-Za-z0-9_]*`, max 64 chars, reserved words rejected). Renaming a declared variable rewrites all `{{oldName}}` and `{{oldName.*}}` tokens in the subject and in text/heading/button/html blocks — including inside block helpers (`{{#if}}`, `{{#each}}`, `{{#unless}}`, `{{#with}}`).
+- **Usage indicators.** Each row shows how many times the variable is referenced, or "Unused in body" if the declared name never appears. Tokens found in the body that aren't declared surface at the top of the panel with a one-click "add as variable" action.
+- **Insert at cursor.** Focus a text/heading/button/html editor or the subject input, then click the Insert button next to a variable to splice `{{name}}` at the caret.
+- **Sample values.** Each row has an optional `sampleValue` field that travels with the template (persisted on `editor_config.root.data.variables[].sampleValue`). In Preview mode, `{{name}}` and `{{name.*}}` tokens in the subject and in text/heading/button/html blocks render with the sample value substituted in; block helpers (`{{#if}}`, `{{#each}}`, …) are stripped so their content renders inline, but the control flow is not evaluated. Edit mode always shows the raw tokens.
+
 #### 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:
@@ -113,6 +123,41 @@ type SavePayload = {
 
 The `renderToStaticMarkup` and `renderToText` utilities are also exposed publicly for consumers that need to re-render outside the save flow (e.g. batch jobs).
 
+#### Image upload and library (BYO backend)
+
+The editor delegates image storage to the consumer through three optional callbacks. When omitted, the corresponding UI is hidden and URL paste remains the fallback.
+
+```ts
+type UploadedImage = {
+  url: string;
+  width?: number;
+  height?: number;
+  alt?: string;
+};
+
+type LibraryImage = UploadedImage & {
+  thumbnailUrl?: string;
+  uploadedAt?: string;
+};
+```
+
+- **`uploadImage(file)`** — receives a single `File`, uploads it (S3, R2, Bunny, presigned PUT, etc.), and returns the public `url` plus optional intrinsic dimensions and alt text. Wires up: the Upload button in the Image inspector, drag-and-drop of an image file onto the canvas, and paste-image-from-clipboard.
+- **`loadImages()`** — returns the consumer's image list for the "Library" picker dialog (grid + filter by alt/URL).
+- **`deleteImage(url)`** — removes an image from the library; surfaces a delete button on hover in the picker.
+
+Reference upload handler:
+
+```ts
+const uploadImage = async (file: File) => {
+  const form = new FormData();
+  form.append('file', file);
+  const res = await fetch('/api/images', { method: 'POST', body: form });
+  return res.json(); // { url, width, height }
+};
+```
+
+Newly uploaded images get their `width` / `height` set on the resulting Image block — important for Outlook, which needs explicit dimensions to lay the email out before images load.
+
 | `theme` | object | theme.ts | Custom theme for the EmailEditor, must be a Material UI theme object |
 
 #### Imperative API