@emailmaker/emailmaker 1.1.85-dev.6 → 1.1.85-dev.8

package/README.md

@@ -214,10 +214,13 @@ const editor = emailmaker.create({
 await editor.ready;
 ```
 
-Ручку можно сразу положить в своё хранилище, подписаться на события или вызвать `destroy()`. До
-`ready` она ведёт себя так:
+Ручку можно сразу положить в своё хранилище, подписаться на события или вызвать `destroy()`.
 
-| что | до готовности |
+Ручка привязывается к редактору, как только он собран, — ещё до показа письма из `content`: так
+вызовы из обработчиков (как `compileEmail()` выше) доходят до редактора. После привязки все вызовы
+идут прямо в редактор. До привязки ручка ведёт себя так:
+
+| что | до привязки |
 | --- | --- |
 | подписки `handle*` | запоминаются и цепляются до первого события — ничего не теряется |
 | асинхронные методы (`show`, `compileEmail`, `getEmailSnapshot`, …) | ждут готовности и выполняются |
@@ -231,6 +234,15 @@ await editor.ready;
 редактора. Если узел уже переиспользовал другой владелец, `destroy()` прежнего редактор не трогает —
 забирает только свои подписки.
 
+Между привязкой и `ready` письмо может быть ещё не показано. Если нужен именно показанный документ —
+например, снимок `getEmailSnapshot()`, — дождитесь `ready`.
+
+Следующий `create()` или `init()` в тот же узел переиспользует его редактор со своими опциями (если
+первый ещё стартует — дожидается его): оба вызова завершаются успешно, редактор принадлежит
+последнему. Прежняя ручка с этого момента не владелец: события ей больше не приходят, а её `destroy()`
+только отвязывает её и редактор не трогает. `destroy()` последней ручки уничтожает редактор — даже до
+её `ready`.
+
 Ошибка инициализации приходит отказом `ready`. Если ручку создали, а `ready` не ждут, такая ошибка
 всплывёт в консоли как необработанная — это намеренно: иначе о том, что редактор не поднялся, не
 узнать. Исключение — `destroy()` до готовности: этот отказ ожидаемый и не шумит.
@@ -620,7 +632,7 @@ emailmaker.init({
 | handleSaveButtonClick | Клик по основной кнопке (например «Сохранить»). |
 | handleNextButtonClick | Клик по «Далее». |
 | handlePreviousButtonClick | Клик «Назад» в шапке. |
-| handleEmailInit | Инициализирован контур письма. |
+| handleEmailInit | Письмо показано на холсте. Приходит на каждое наполнение холста новым содержимым — при старте и при каждом `show()` с другим письмом; повтор того же показа и перезаливка холста события не дают. Однократные действия («сохранить при первом открытии») на нём не стройте. |
 | handleEmailChanged | Изменился параметр письма. |
 | handleHtmlChanged | Изменился HTML-код. |
 | handleSubjectChanged | Изменилась тема (особая подпись — см. типы). |
@@ -635,7 +647,7 @@ emailmaker.init({
 | handleDestroy | Перед уничтожением экземпляра. |
 | handleLoad | Завершена загрузка экземпляра; можно безопасно вызывать **`getEmail`** и др. |
 | handleLoadImage | Загрузка изображения пользователем; **`handleFileProxy`**, **`handleUrlProxy`** — прокси файлов/URL при необходимости. Вернуть URL; исключение из обработчика = отказ (редактор не грузит картинку на свой бэкенд), **`undefined`** — редактор дозагружает сам, кроме замкнутого контура (**`standaloneKey`**). |
-| handleNotify | Произвольное уведомление. |
+| handleNotify | Произвольное уведомление. Среди ошибок — `TEMPLATE_READ_ERROR` (`data: { templateId }`): шаблон по `templateId` не прочитался, письмо открыто без него. Приходит один раз на шаблон за жизнь редактора; заголовка у события нет и всплывающего сообщения редактор не показывает — покажите своё, если пользователю нужно знать. |
 | handleError | Ошибка (можно переопределить UI). |
 | handleSuccess | Успешная операция. |
 | handleReadLocale | Язык интерфейса (**`AppConfigMixin`**). Каталог возвращается текстом **`.po`**, JSON-строкой или готовым объектом **`LocaleData`**. |