@mjml-agent-editor/editor 0.1.17 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@ on the canvas.
 | -------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------ |
 | `@mjml-agent-editor/editor`            | stores, `EditorHeader`, `ChatPanel`, `CanvasComments`, types | Safe to import anywhere                                |
 | `@mjml-agent-editor/editor/ui`         | the shadcn primitives and `cn`                               | Light; no canvas                                       |
-| `@mjml-agent-editor/editor/canvas`     | `EmailEditor`                                                | **Browser only** — GrapesJS touches `window` at import |
+| `@mjml-agent-editor/editor/canvas`     | `EmailEditor`, `blockProblems`                               | **Browser only** — GrapesJS touches `window` at import |
 | `@mjml-agent-editor/editor/styles.css` | editor chrome stylesheet                                     | Import from your Tailwind entry                        |
 
 The split is not cosmetic. With a single barrel, a layout file importing a tooltip provider
@@ -121,6 +121,37 @@ storage would otherwise be handing out a way round its own cap.
 Without a library the picker takes URLs only. The editor never inlines a file as base64:
 most mail clients block `data:` images, and every agent turn would pay for the bytes.
 
+## Your own sections
+
+`EmailEditor` takes `blocks`: sections of your own, listed in the palette after the built-in
+blocks, under `blockCategorySections`. Each is one `<mj-section>` of MJML; once dropped it is
+ordinary MJML that the agent edits like any other section, and it gets its `sec-*` id then.
+
+```tsx
+const BLOCKS = [{ id: "footer", label: "Footer", mjml: FOOTER_MJML }] satisfies SectionBlock[];
+
+<EmailEditor docId={docId} blocks={BLOCKS} /* … */ />;
+```
+
+The agent compiles the whole email strictly on every write, so a section the editor cannot
+keep would block it in every email it is dropped in. `blockProblems(mjml)` says why a block
+cannot be offered — it is not strict MJML, not exactly one section, carries a `sec-*`/`obj-*`
+id, a link whose scheme is not http, https, mailto, tel or sms, or a `data:` image, holds markup
+the editor drops, or uses a tag a section here cannot hold (`mj-table`, `mj-hero`, accordion
+and carousel, which the editor cannot edit; `mj-wrapper` and `mj-raw`). The editor leaves such
+a block out and logs why; call it in a test of your catalog to find out before your users do.
+It needs a DOM, so run that test under jsdom. Labels are plain text. `blocks` is read once,
+when the editor starts.
+
+Every tile, built-in or yours, also works from the keyboard: Tab to it, and Enter or Space
+adds it after the selected element or section (an element with nothing selected gets a
+section of its own), selects it and announces it.
+
+What an email loads from elsewhere: no built-in block carries a sample picture, but social
+icons without a `src` of their own come from `www.mailjet.com`, and text without a
+`font-family` gets MJML's default, Ubuntu from `fonts.googleapis.com`. Both reach every
+reader's mail client, so name them wherever you list who receives your users' data.
+
 ## Copy
 
 Every word the editor renders comes from a dictionary with English defaults, so a host
@@ -138,10 +169,14 @@ building in another language overrides rather than forks:
 >
 ```
 
-Overrides are shallow-merged, so anything omitted stays English. `toolLabels` is the one
-exception and merges key by key — renaming one step would otherwise silently drop the other
-eight. `DEFAULT_LABELS` and the `EditorLabels` type are exported if you want to see the full
-list or build a complete translation.
+Overrides are shallow-merged, so anything omitted stays English. The maps keyed by an id
+are the exception and merge key by key, so translating one entry keeps the others:
+`toolLabels` (by agent tool), `blockLabels` (by block id, e.g. `mj-2-columns`),
+`elementNames` (by MJML tag) and `inspectorLabels` (the Settings tab's field and option
+names, and help as `<key>.help`). `DEFAULT_LABELS` and the `EditorLabels` type are exported
+if you want to see the full list or build a complete translation; for `inspectorLabels` the
+keys in `DEFAULT_LABELS.inspectorLabels` are the whole set. Font and brand names (Arial,
+Facebook) are shown as they are and have no key.
 
 New keys arrive with new features, including in 0.1.x releases. They always have English
 defaults, so a host passing `Partial<EditorLabels>` picks them up untouched; a host that