@emailmaker/emailmaker 1.1.109 → 1.2.3

package/README.md

@@ -555,8 +555,11 @@ HTML-разметка письма.
 | nextButtonText                         | Текст на второстепенной кнопке.                                             | ''                    |
 | saveButtonEnabled                      | Показ основной кнопки.                                                      | true                  |
 | saveButtonText                         | Текст основной кнопки.                                                      | ''                    |
+| saveHotkeyEnabled                      | Сохранение по Ctrl+S / Cmd+S. `false` отключает его; диалог браузера «Сохранить страницу» всё равно не открывается. | true |
 | commandButtonsEnabled                  | Показ основной и второстепенной кнопки.                                     | true                  |
 |                                        |                                                                             |                       |
+| lockEditor                             | Режим только для чтения: письмо нельзя изменить. Закрывает холст, редактор кода, поля темы и прехедера, импорт, отмену и повтор (кнопки и клавиши), историю версий, настройки письма и UTM-метки, ИИ-чат, конвертер раскладки и аннотации Gmail. Кнопки остаются на месте, но неактивны; иконка ИИ у темы и прехедера скрывается. Методы API (`show`, `setEmail`, отмена через API) не закрываются. Переключается через `setConfig`. | false |
+|                                        |                                                                             |                       |
 | sidePanelFloating                      | Плавающая боковая панель.                                                   | true                  |
 | desktopMobileSwitchRule                | Полоса переключения режимов.                                                | true                  |
 | desktopMobileSwitchPanel               | Панель переключения режимов.                                                | false                 |
@@ -771,7 +774,8 @@ emailmaker.init({
 | handleShareEmail | Поделиться. |
 | handleLivePreviewEmail | Живой предпросмотр. |
 | handlePreviewEmail | Предпросмотр. |
-| handleValidate | Результат проверки кода (**`CodeError[]`**). |
+| handleValidate | Ошибки редактора кода (**`CodeError[]`**) — то, что он подчёркивает. Приходит после проверки текста в редакторе: пока ошибки есть — на каждую правку, и один раз, когда они исчезли; если ошибок не было и нет — не приходит. Только после того, как режим кода хоть раз открывали. Проверить письмо по требованию — **`validateCode()`**. |
+| handleImportValidate | Ошибки разметки импортируемого файла (**`{ errors: CodeError[], fileName }`**), найденные до разбора браузером: браузер молча «чинит» сбитую разметку, и редактор ошибок уже не увидит. Файл проверяется, только если на событие есть подписчики. Импорт событие не задерживает и не отменяет; у чистого файла **`errors`** пустой. |
 | handleTestEmailSend | Отправка тестового письма. |
 | handleTestEmailModal | Открыто окно тестовой отправки. |
 | handleDestroy | Перед уничтожением экземпляра. |
@@ -783,9 +787,60 @@ emailmaker.init({
 | handleReadLocale | Язык интерфейса (**`AppConfigMixin`**). Каталог возвращается текстом **`.po`**, JSON-строкой или готовым объектом **`LocaleData`**. |
 | handleTranslate | Пользовательский перевод строк. |
 | handleLimitUsage | Отображение квот / лимитов. |
+| handleAnalyticsEvent | Действие пользователя в редакторе — для вашей аналитики; см. ниже. |
 
 Полный перечень и сигнатуры — в **`emailmaker.d.ts`** (**`ExportedApi.DataMixin.Events`** и смежные миксины).
 
+#### Аналитика: `handleAnalyticsEvent`
+
+Редактор сообщает о действиях пользователя — для вашей аналитики (Amplitude, GA и т. п.). Событие —
+**`{ name, properties }`**:
+
+- **`name`** — имя вида `editor_<объект>_<действие>`: `editor_email_saved`, `editor_layout_convert_succeeded`;
+- **`properties`** — только закрытые списки значений, числа и флажки. Идентификаторов, имён, текста
+  письма и адресов в событиях нет. Связать событие со своим письмом или пользователем — ваша часть:
+  добавьте свой идентификатор при передаче в аналитику.
+
+Обработчик не ждут: его результат не используется, исключение в нём на редактор не влияет. События
+приходят независимо от **`pushToGTM`**. Частые события — правка настройки элемента, ширина холста —
+приходят одним, после паузы.
+
+```javascript
+emailmaker.init({
+  element: '#editor',
+  content: { email: { id: '1' } },
+  getAuthToken,
+  handleAnalyticsEvent: ({ name, properties }) => {
+    amplitude.track(name, { ...properties, letter_id: currentLetterId });
+  },
+});
+```
+
+Конвертация чужой вёрстки (BeeFree, Stripo и прочей):
+
+| Событие | Когда | Свойства |
+| --- | --- | --- |
+| `editor_layout_convert_offered` | Показано предложение сконвертировать | `source`, `trigger` |
+| `editor_layout_convert_declined` | Предложение отклонено | `source`, `trigger`, `never_suggest` |
+| `editor_layout_convert_started` | Начата попытка | `source`, `method`, `trigger` |
+| `editor_layout_convert_succeeded` | Результат в редакторе | `source`, `method`, `trigger`, `duration_ms`, `fallback_to_ai` |
+| `editor_layout_convert_failed` | Попытка не удалась | `source`, `method`, `trigger`, `duration_ms`, `error_code` |
+
+`source` — `beefree` / `stripo` / `unknown`; `method` — `algorithm` / `ai`; `trigger` — `prompt` (предложение
+при открытии письма), `import`, `menu`, `retry`.
+
+Остальные события:
+
+| Область | События |
+| --- | --- |
+| Письмо и блок | `editor_email_saved`, `editor_block_saved`, `editor_back_clicked`, `editor_email_deleted`, `editor_email_delete_clicked`, `editor_email_delete_modal_opened`, `editor_email_duplicate_clicked`, `editor_email_duplicated`, `editor_email_import_clicked`, `editor_email_imported`, `editor_email_exported`, `editor_email_locked`, `editor_email_unlocked`, `editor_block_locked`, `editor_block_unlocked` |
+| Холст и панели | `editor_element_added`, `editor_element_setting_changed`, `editor_canvas_resized`, `editor_pane_tab_opened`, `editor_config_mode_changed`, `editor_mode_changed`, `editor_code_mode_activated`, `editor_breadcrumb_clicked` |
+| Проверки и предпросмотр | `editor_code_checked`, `editor_links_checked`, `editor_images_checked`, `editor_spam_checked`, `editor_preview_opened`, `editor_test_email_modal_opened`, `editor_test_email_sent`, `editor_email_shared`, `editor_inbox_tests_opened`, `editor_version_history_opened`, `editor_web_version_opened` |
+| ИИ и обсуждение | `editor_ai_message_sent`, `editor_ai_reply_received`, `editor_ai_role_selected`, `editor_ai_subject_inserted`, `editor_ai_preheader_inserted`, `editor_comment_sent`, `editor_ai_image_generation_started` |
+
+Свойства каждого события и их значения — в **`emailmaker.d.ts`**, **`ExportedApi.DataMixin.AnalyticsEventMap`**.
+Событие приходит, только если соответствующая функция включена в конфигурации.
+
 #### Восстановление автосохранения
 
 - Восстановленное содержимое редактор считает текущим: событий правки (**`handleEmailChanged`**, **`handleHtmlChanged`**) не будет, пока пользователь не изменит письмо. Автосохранение при этом остаётся у вас, поэтому при следующем открытии письмо восстановится снова.
@@ -899,6 +954,7 @@ emailmaker.init({
 | `trashPath`                 | `string`  | Путь к корзине/папке для удаленных файлов                   | -            |
 | `tempPath`                  | `string`  | Путь к временной папке для загрузок                         | -            |
 | `useSoftDelete`             | `boolean` | Включить программное мягкое удаление                        | `false`      |
+| `trashSupportsFolders`      | `boolean` | Корзина принимает папки (при `useSoftDelete`)               | `true`       |
 | `ensureFolderTrailingSlash` | `boolean` | Добавлять к путям папок завершающий слэш                    | `true`       |
 | `validateDuplicates`        | `boolean` | Проверка на существование при операциях с файлами и папками | -            |
 
@@ -938,6 +994,7 @@ emailmaker.init({
 ##### Важные примечания
 
 - **Мягкое удаление**: Когда `useSoftDelete=true`, операции удаления перемещают элементы в `trashPath`
+- **Корзина без папок**: Если бэкенд не принимает папки в корзине, задайте `trashSupportsFolders=false`: при удалении папки файлы всего её поддерева переносятся в корзину плоским списком (совпавшее имя получает номер, `photo (1).png`, если реализован `renameItem`), а опустевшие папки удаляются навсегда. Если хоть один файл не перенёсся, папка не удаляется
 - **Корневая папка**: Используйте `rootId` или пустую строку для операций с корневой папкой
 - **Разрешение путей**: `trashPath` и `tempPath` преобразуются в реальные идентификаторы папок
 - **Загрузка по URL**: Должна проверять, существует ли файл уже на текущем сервере