@emailmaker/emailmaker 1.1.85-dev.10 → 1.1.85-dev.11

package/README.md

@@ -58,7 +58,7 @@ antd и ui-kit — иначе интерфейс падает при отрис
 | --- | --- |
 | **`init`** | Обязательно **`content`**. Сигнатура: **`init(options)` → `Promise<Instance>`**. |
 | Namespace vs **instance** | У модуля **`emailmaker`** — в основном **`init`** (+ именованные ESM-экспорты). **`setConfig`**, **`show`**, **`save`**, **`destroy`** — у **экземпляра** после **`init`**. |
-| Повтор на том же DOM | Повторный **`init`** на тот же узел переиспользует редактор (**`reset`**); если прежний ещё стартует — дожидается его. Оба вызова успешны, владеет последний. |
+| Повтор на том же DOM | Повторный **`init`** на тот же узел отдаёт **тот же объект** и применяет опции, как **`setConfig`**. Если прежний ещё стартует — его промис отклоняется **`AbortError`**, успешен второй. **`destroy()`** через любую ссылку уничтожает редактор. Свой объект на вызов — опция **`ownership: 'counted'`**. |
 | События | **`instance.handle*(…)`** обычно возвращает **отписку**. **`handleSubjectChanged`** / **`handlePreheaderChanged`** — другая сигнатура (см. типы). |
 | Async | Колбэки и **`getAuthToken`** могут быть **`async`**; ошибки — через **`handleError`** или свою логику. |
 | Сборка | Без штатного плагина Webpack/Vite задайте **`publicPath`** (**`__emailmaker__`**). Бандл крупный (React, Monaco и др.). |
@@ -216,11 +216,12 @@ emailmaker
 
 КОД_ПИСЬМА можно взять из <a href="https://emcdn.ru/plugin/new-email.html" target="_blank">нашего образца</a> или вставить HTML-код своего письма.
 
-### Ручка редактора: `create()`
+### Объект редактора сразу: `create()`
 
 `init()` возвращает редактор, только когда он готов и письмо из `content` уже показано. Обработчики
 при этом срабатывают раньше — внутри `init()`, — и сослаться в них на редактор нельзя: переменная
-ещё не присвоена. `create()` отдаёт **ручку** сразу, синхронно, а готовность — отдельным промисом:
+ещё не присвоена. `create()` отдаёт **объект редактора** сразу, синхронно, а готовность — отдельным
+промисом:
 
 ```javascript
 const editor = emailmaker.create({
@@ -228,7 +229,7 @@ const editor = emailmaker.create({
   element: '#editor',
   content: { email },
   handleEmailInit: async () => {
-    // Ручка уже есть — к моменту события она присвоена.
+    // Объект уже есть — к моменту события он присвоен.
     const compiled = await editor.compileEmail(undefined, { amp: true });
     await saveOnYourSide(compiled);
   },
@@ -236,11 +237,13 @@ const editor = emailmaker.create({
 await editor.ready;
 ```
 
-Ручку можно сразу положить в своё хранилище, подписаться на события или вызвать `destroy()`.
+Это обычный объект, как и результат `init()`: все методы — его собственные поля, их видят
+`Object.keys`, spread и `Object.assign`, любой метод можно подменить своим. Объект можно сразу
+положить в своё хранилище, подписаться на события или вызвать `destroy()`.
 
-Ручка привязывается к редактору, как только он собран, — ещё до показа письма из `content`: так
+Объект привязывается к редактору, как только тот собран, — ещё до показа письма из `content`: так
 вызовы из обработчиков (как `compileEmail()` выше) доходят до редактора. После привязки все вызовы
-идут прямо в редактор. До привязки ручка ведёт себя так:
+идут прямо в редактор. До привязки объект ведёт себя так:
 
 | что | до привязки |
 | --- | --- |
@@ -249,31 +252,20 @@ await editor.ready;
 | `setEmailMeta`, `setBlockMeta`, `notify` | применяются при готовности, по порядку |
 | `getElement()` | узел из опций, если он передан элементом; для селектора — `undefined` |
 | `getCodeErrors()` | пустой список |
-| `getConfig()`, `use()`, `container`, `undoRedoService` | бросают — дождитесь `ready` или используйте `useAsync()` |
+| `getConfig()`, `use()` | бросают понятную ошибку — дождитесь `ready` или используйте `useAsync()` |
+| поля `container`, `undoRedoService` | `undefined`; чтение не бросает |
 | `destroy()` | отменяет инициализацию, `ready` отвергается с `AbortError` |
 
-После `destroy()` ручка отвязана: её подписки сняты, а методы отвергаются, как у уничтоженного
-редактора. Если узел уже переиспользовал другой владелец, `destroy()` прежнего редактор не трогает —
-забирает только свои подписки.
-
 Между привязкой и `ready` письмо может быть ещё не показано. Если нужен именно показанный документ —
 например, снимок `getEmailSnapshot()`, — дождитесь `ready`.
 
-Следующий `create()` или `init()` в тот же узел переиспользует его редактор со своими опциями (если
-первый ещё стартует — дожидается его): оба вызова завершаются успешно, редактор принадлежит
-последнему. Прежняя ручка с этого момента не владелец: события ей больше не приходят, а её `destroy()`
-только отвязывает её и редактор не трогает. `destroy()` последней ручки уничтожает редактор — даже до
-её `ready`.
-
-Если новый вызов передаёт те же данные, что и прежний, — то же письмо, конфигурацию, пользователя и
-тот же набор обработчиков, пусть даже новыми функциями, как при каждой перерисовке компонента, —
-редактор опций заново не применяет: письмо не перепоказывается, `handleSetOptions` и
-`handleOptionsChanged` не приходят, события уходят в обработчики нового вызова.
-
-Ошибка инициализации приходит отказом `ready`. Если ручку создали, а `ready` не ждут, такая ошибка
+Ошибка инициализации приходит отказом `ready`. Если объект создали, а `ready` не ждут, такая ошибка
 всплывёт в консоли как необработанная — это намеренно: иначе о том, что редактор не поднялся, не
 узнать. Исключение — `destroy()` до готовности: этот отказ ожидаемый и не шумит.
 
+Повторный `create()` или `init()` в тот же узел описан ниже, в разделе
+[«Повторный init() в тот же узел»](#повторный-init-в-тот-же-узел).
+
 `await emailmaker.create(options).ready` — это ровно то, что делает `init(options)`: переходить с
 одного на другое не обязательно.
 
@@ -387,36 +379,76 @@ await emailmaker.init({ element: '#editor', content, getAuthToken });
 | метаданные и состояние документа | да |
 | вёрстка письма | заменяется той, что передали в `content` |
 
-### Уборка, когда владельцев несколько
+### Повторный init() в тот же узел
 
-Один контейнер переживает несколько владельцев: страница подняла редактор, следующая вошла в тот же
-контейнер и получила его же. Такое бывает и без вашего умысла — React размонтирует прежнюю страницу
-**после** того, как смонтировал новую, а в StrictMode вызывает эффект дважды.
+Как ведёт себя повторный `init()` или `create()` в тот же контейнер, задаёт опция `ownership`.
 
-Поэтому `destroy()` уничтожает редактор только у последнего вошедшего. Уборка прежнего владельца
-означает «я больше не держу его» и живой экземпляр не трогает:
+**По умолчанию (`ownership: 'single'`) — как в 1.1.89.** У контейнера один объект редактора:
 
 ```javascript
 const first = await emailmaker.init({ element: '#editor', content });
-const second = await emailmaker.init({ element: '#editor', content });  // тот же редактор
+const second = await emailmaker.init({ element: '#editor', content, config });
+first === second; // true
 
-first.destroy();   // ничего не уничтожает: владение уже у second
-second.destroy();  // уничтожает
+second.destroy(); // уничтожает редактор — через любую ссылку
 ```
 
-Держите то, что вернул **последний** `init()`. Прежде уборка опоздавшей страницы убивала редактор
-под ногами у новой, и следующий показ падал с `DestroyedInstanceError`.
+- Повторный вызов применяет опции, как `setConfig`. Обработчики из опций подменяются сразу: события,
+  которые придут дальше, уходят в обработчики нового вызова. Подписки, сделанные через объект
+  (`editor.handleSaveEmail(cb)`), живут — объект ведь тот же.
+- Письмо показывается заново, только если оно отличается от последнего, которое вы задали сами —
+  через `init`, `show` или `reset`. `init(A)` → `show(B)` → `init(A)` вернёт письмо A. `init(A)` →
+  `init(A)` письмо не перерисует, и правки пользователя останутся.
+- Если вызов передаёт те же данные, что и прежний, — то же письмо, конфигурацию, пользователя и тот же
+  набор обработчиков, пусть даже новыми функциями, как при каждой перерисовке компонента, — опции
+  заново не применяются: `handleSetOptions` и `handleOptionsChanged` не приходят, токен не
+  перезапрашивается.
+- Вызов, сделанный, пока прежний ещё стартует, вытесняет его: промис прежнего отклоняется
+  `AbortError` (`emailmaker.isSupersededInitError(error)`), успешен только новый. Так ведёт себя и
+  React StrictMode без отдельной уборки.
+- `destroy()` через любую ссылку уничтожает редактор, а `handleDestroy`, подписанный через объект,
+  срабатывает.
+
+**`ownership: 'counted'` — свой объект на каждый вызов.** Нужен, когда редактор в одном контейнере
+делят несколько частей приложения: страница подняла его, следующая вошла в тот же контейнер, а уборка
+прежней приходит позже — React размонтирует прежнюю страницу **после** того, как смонтировал новую, а
+в StrictMode вызывает эффект дважды.
+
+```javascript
+const first = emailmaker.create({ element: '#editor', content, ownership: 'counted' });
+const second = emailmaker.create({ element: '#editor', content, ownership: 'counted' });
+await Promise.all([first.ready, second.ready]); // оба успешны, редактор один
+
+first.destroy();  // снимает только долю first и его подписки
+second.destroy(); // последняя доля: редактор уничтожается чуть позже
+```
+
+- Каждый вызов получает свой объект со всеми методами общего редактора и держит долю во владении.
+  Подписки объекта живут до его `destroy()`.
+- `destroy()` снимает долю этого объекта. Редактор уничтожается, когда долей не осталось, — с короткой
+  отложкой, чтобы уборка и новый вызов подряд (StrictMode) его не пересоздавали.
+- Действуют опции и обработчики последнего вызова. Уходит его доля — обработчики из опций переходят к
+  последнему оставшемуся владельцу; письмо и настройки остаются как есть.
+- `emailmaker.getInstance(element)` отдаёт объект последнего вызова.
+
+**Смешивать режимы можно.** Вызов без флага держит редактор, пока не вызовут `destroy()` его объекта,
+и получает общий объект контейнера. Доли `counted` живут поверх. `destroy()` объекта без флага
+уничтожает редактор со всеми долями — их объекты дальше ведут себя как после `destroy()`. В режиме
+разработки смешивание отмечается предупреждением в консоли.
+
+**Если повторный вызов не стартовал** (упал токен или `app_init`, отменили через `signal`), отклоняется
+только он: редактор остаётся с прежними опциями и прежним письмом, восстановленным из снимка (текст и
+шапка; история отмен сбрасывается). Если вернуть не удалось, редактор уничтожается, а методы прежних
+объектов бросают `EditorStartFailedError` с причиной в `cause` — поднимите редактор новым `init()`.
+Отмена `signal` прежнего вызова после того, как пришёл новый, редактор не трогает.
 
-Если новый `init()` не стартовал (упал или его отменили через `signal`), редактор возвращается
-прежнему владельцу: с его опциями и его письмом, восстановленным из снимка (текст и шапка; история
-отмен сбрасывается). Если вернуть не удалось, редактор уничтожается, а методы прежнего экземпляра
-бросают `EditorStartFailedError` с причиной в `cause` — поднимите редактор новым `init()`.
+`init()` в **другой** контейнер поднимает новый редактор.
 
 # Конфигурация
 
 Конфигурация задаётся объектом с несколькими уровнями вложенности: внешний вид редактора, стартовое содержимое и обработчики событий.
 
-Повторный вызов **`init`** на **тот же DOM-элемент** внутри приводит к **`reset`** с новыми опциями — не запускайте параллельно два **`init`** на один контейнер.
+Повторный вызов **`init`** на **тот же DOM-элемент** отдаёт тот же объект и применяет новые опции — см. [«Повторный init() в тот же узел»](#повторный-init-в-тот-же-узел).
 
 ### element
 
@@ -744,7 +776,7 @@ emailmaker.init({
 | handleDestroy | Перед уничтожением экземпляра. |
 | handleLoad | Завершена загрузка экземпляра; можно безопасно вызывать **`getEmail`** и др. |
 | handleLoadImage | Загрузка изображения пользователем; **`handleFileProxy`**, **`handleUrlProxy`** — прокси файлов/URL при необходимости. Вернуть URL; исключение из обработчика = отказ (редактор не грузит картинку на свой бэкенд), **`undefined`** — редактор дозагружает сам, кроме замкнутого контура (**`standaloneKey`**). |
-| handleNotify | Произвольное уведомление. Среди ошибок — `TEMPLATE_READ_ERROR` (`data: { templateId }`): шаблон по `templateId` не прочитался, письмо открыто без него. Приходит один раз на шаблон за жизнь редактора; заголовка у события нет и всплывающего сообщения редактор не показывает — покажите своё, если пользователю нужно знать. |
+| handleNotify | Произвольное уведомление. Среди предупреждений (`type: 'warning'`) — `TEMPLATE_READ_ERROR` (`data: { templateId }`): шаблон по `templateId` не прочитался, письмо открыто без него. Приходит один раз на шаблон за жизнь редактора, в `handleError` не попадает; заголовка у события нет и всплывающего сообщения редактор не показывает — покажите своё, если пользователю нужно знать. |
 | handleError | Ошибка (можно переопределить UI). |
 | handleSuccess | Успешная операция. |
 | handleReadLocale | Язык интерфейса (**`AppConfigMixin`**). Каталог возвращается текстом **`.po`**, JSON-строкой или готовым объектом **`LocaleData`**. |