@retailcrm/embed-ui-v1-endpoint 0.9.26 → 0.9.28

package/bin/embed-ui-v1-endpoint.mjs

@@ -168,9 +168,12 @@ When working with \`${PACKAGE_NAME}\` in this project:
 7. Then read the relevant \`embed-ui-v1-endpoint://targets/<encoded-target>\` resource before answering or changing code related to that target.
 8. For widget UI composition, keep inline target content compact: prefer \`UiToolbarButton\`, \`UiToolbarLink\`, short text, and icons; move complex UI into \`UiModalSidebar\` or \`UiModalWindow\`.
 9. If \`@retailcrm/embed-ui-v1-components\` is installed, read its widget composition docs before building widget UI.
-10. A project \`.mcp.json\` may require restarting or reconnecting the AI client before MCP resources appear in the current session.
-11. If MCP resources are not available, use the generated YAML profiles from \`./node_modules/${PACKAGE_NAME}/docs/targets/*.yml\` as the fallback source.
-12. Prefer target profiles over guessing target placement, contexts, or semantic intent from names alone.
+10. Before choosing RetailCRM system \`menu\` or \`parentMenuItemCode\`, read \`https://docs.retailcrm.ru/api/ru/RetailCRM/jsApiMethods/navigation\`; do not guess menu codes from section names or stale examples.
+11. A project \`.mcp.json\` may require restarting or reconnecting the AI client before MCP resources appear in the current session.
+12. If MCP resources are not available, use the generated YAML profiles from \`./node_modules/${PACKAGE_NAME}/docs/targets/*.yml\` as the fallback source.
+13. Prefer target profiles over guessing target placement, contexts, or semantic intent from names alone.
+14. Keep page switch/root components thin; move shared locale synchronization and context plumbing into composables or plugins when several embed pages need them.
+15. Prefer domain-specific frontend API helpers over one generic page-level transport helper, and preserve structured API errors.
 
 Suggested MCP stdio server configuration:
 

package/docs/define-page-runner.md

@@ -61,6 +61,26 @@ const pageRunner = definePageRunner({
 Если ошибка видна только в minified bundle, соберите или отдайте dev bundle без минификации до изменения кода
 по догадке.
 
+## Shared page setup
+
+Если runner обслуживает несколько embed pages, держите root/switch component максимально тонким: он выбирает
+компонент страницы по `code`, но не должен дублировать context plumbing, синхронизацию локали и API-адаптеры
+каждой страницы.
+
+Для i18n используйте общий composable или plugin, который синхронизирует remote locale из settings/context
+источника, принятого в проекте. Если локаль нужна нескольким embed pages, не копируйте один и тот же watch/load
+код в каждую страницу и не прячьте его в page switch без явной причины.
+
+Для admin pages с несколькими сущностями предпочитайте тонкие domain helpers вместо одного безымянного
+`callAdminApi`: `loadSettings`, `saveSettings`, `loadSpecialties`, `saveSpecialist`, `deleteSpecialist` и т.п.
+Такие helpers должны сохранять transport details внутри integration layer, но отражать доменный контракт страницы
+в именах и типах.
+
+Ошибки API сохраняйте структурированными: status, field errors, error codes и machine-readable детали не должны
+теряться при преобразовании в UI state. Если API возвращает error codes, frontend может переводить их в локали UI;
+готовый backend message допустим как fallback или специальное продуктовое требование, но не должен быть
+единственным typed contract для сложной формы.
+
 ## `beforeMount`
 
 `beforeMount` вызывается после `app.use(pinia)` и до `app.mount(...)`.

package/docs/menu-placements.md

@@ -16,6 +16,19 @@
 `menu item` не равен `target`. Меню открывает полноценную встраиваемую страницу по `code`, а `target`
 используется для виджетов, которые встраиваются внутрь уже существующей CRM-страницы.
 
+## Справочник системных меню RetailCRM
+
+Коды системных меню и родительских пунктов меню RetailCRM обязательно сверяйте с актуальным
+JSON-справочником:
+
+https://docs.retailcrm.ru/api/ru/RetailCRM/jsApiMethods/navigation
+
+Этот ресурс отдаёт фактические `menus[]` и `menu_items[]`, которые использует документация RetailCRM.
+Не подбирайте `menu` и `parentMenuItemCode` по названию раздела или по старым примерам: перед добавлением
+или изменением страницы перечитайте справочник и выберите код из него. Например, для страницы в настройках
+валидная пара обычно выглядит как `menu: "private_main_menu"` и `parentMenuItemCode: "settings"`, а для
+страницы в продажах — `menu: "activity_main_menu"` и подходящий пункт из `menu_items[]` этого меню.
+
 ## Что фиксировать в справочнике проекта
 
 Для каждого пункта меню указывайте:
@@ -59,7 +72,7 @@
 `menu` обязателен для опубликованной страницы: без него backend не сможет открыть route вида
 `/modules/<module-code>/<page-code>`. Для страниц в разделе настроек обычно используется
 `menu: "private_main_menu"` и `parentMenuItemCode: "settings"`. Для страниц в разделе продаж используйте
-`menu: "activity_main_menu"` и соответствующий parent menu item, например `orders`.
+`menu: "activity_main_menu"` и соответствующий parent menu item из справочника RetailCRM.
 
 CRM также использует hierarchy из `pages[]` для видимой навигации и breadcrumb-like поведения. Сначала
 моделируйте нужную иерархию через `menu`, `parentMenuItemCode` и `menuItemOrdering`; локальные ссылки внутри
@@ -105,7 +118,9 @@ method с обычным JSON-объектом вместо добавления
 
 ## Пример справочника меню
 
-Конкретные `placement`, `item code` и `route` нужно брать из host/manifest расширения.
+Конкретные локальные `placement`, `item code` и `route` нужно брать из host/manifest расширения. Системные
+`menu` и `parentMenuItemCode` для RetailCRM сначала сверяйте со справочником
+`https://docs.retailcrm.ru/api/ru/RetailCRM/jsApiMethods/navigation`.
 
 | Placement | Item code | Label | Page code | Route | Когда использовать |
 | --- | --- | --- | --- | --- | --- |

package/docs/page-routes.md

@@ -98,6 +98,26 @@ const openSettings = (host: HostApi) => {
 }
 ```
 
+## Уведомление перед уходом со страницы
+
+Если странице нужно сообщить host, что уход с текущего URL нежелателен, зарегистрируйте
+`HostApi.onBeforeRouteLeave(hook)`.
+
+```ts
+import type { HostApi } from '@retailcrm/embed-ui-v1-types/host'
+
+const registerLeaveGuard = (host: HostApi, hasUnsavedChanges: () => boolean) => {
+  host.onBeforeRouteLeave(() => !hasUnsavedChanges())
+}
+```
+
+`true` означает, что расширение подтверждает возможность перехода. `false` означает, что расширение
+не подтверждает переход, например потому что пользователь может потерять несохраненные изменения.
+Это не жесткая блокировка навигации со стороны расширения: host может учесть результат, показать
+диалог подтверждения, остаться на текущем URL или проигнорировать мнение расширения, если так устроен
+конкретный сценарий. Метод нужен как общий способ уведомить host о состоянии страницы перед сменой
+маршрута.
+
 Breadcrumb-like navigation для module pages строится CRM из hierarchy в `pages[]`: `menu`,
 `parentMenuItemCode`, `menuItemOrdering` и связанных metadata. Не собирайте breadcrumbs вручную внутри
 страницы, если продуктовая задача явно не просит локальную in-page navigation.
@@ -107,4 +127,5 @@ Breadcrumb-like navigation для module pages строится CRM из hierarc
 - [`menu-placements`](./menu-placements.md) — как связать пункт меню, page `code` и маршрут.
 - [`definePageRunner`](./define-page-runner.md) — как page `code` попадает в компонент.
 - `@retailcrm/embed-ui-v1-contexts` `docs/ru/CONCEPT.md` — общий принцип работы контекстов.
-- `@retailcrm/embed-ui-v1-types` `host.d.ts` — публичный тип host API с `goTo`.
+- `@retailcrm/embed-ui-v1-types` `host.d.ts` — публичный тип host API с `goTo` и
+  `onBeforeRouteLeave`.

package/package.json

@@ -5,7 +5,7 @@
     "embed-ui-v1-endpoint-mcp": "bin/embed-ui-v1-endpoint-mcp.mjs"
   },
   "type": "module",
-  "version": "0.9.26",
+  "version": "0.9.28",
   "description": "Endpoint API for integrations in RetailCRM",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
@@ -101,28 +101,28 @@
   "peerDependencies": {
     "@omnicajs/vue-remote": "^0.2.24",
     "@remote-ui/rpc": "^1.4",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.26",
-    "@retailcrm/embed-ui-v1-types": "^0.9.26",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.28",
+    "@retailcrm/embed-ui-v1-types": "^0.9.28",
     "pinia": "^2.2",
     "vue": "^3.5"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@remote-ui/rpc": "^1.4.7",
-    "@retailcrm/embed-ui-v1-components": "^0.9.26",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.26",
-    "@retailcrm/embed-ui-v1-types": "^0.9.26"
+    "@retailcrm/embed-ui-v1-components": "^0.9.28",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.28",
+    "@retailcrm/embed-ui-v1-types": "^0.9.28"
   },
   "devDependencies": {
     "@retailcrm/image-preview": "^1.0.2",
-    "@vitest/browser": "4.1.3",
-    "@vitest/browser-playwright": "4.1.3",
+    "@vitest/browser": "4.1.8",
+    "@vitest/browser-playwright": "4.1.8",
     "date-fns": "^4.1.0",
     "playwright": "1.58.2",
     "tsx": "^4.21.0",
     "vite": "^7.3.2",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "4.1.3"
+    "vitest": "4.1.8"
   },
   "publishConfig": {
     "access": "public"

package/templates/skills/embed-ui-v1-endpoint-runtime/SKILL.md.txt

@@ -30,12 +30,15 @@ Use this skill before changing JS module endpoint wiring, page registration, wid
 4. Use documented public entrypoints such as `@retailcrm/embed-ui-v1-endpoint/remote`; do not import from `dist/*`, source files, or repository-only paths.
 5. Keep widget inline UI compact; use component package widget composition guidance for UI mounted into CRM targets.
 6. After the first page vertical slice, verify it in the CRM host: menu item, `/modules/<moduleCode>/<pageCode>` route, entrypoint URL, stylesheet URL, and actual frontend mount.
-7. If a runtime error appears only in a minified bundle, switch to a dev bundle or sourcemaps before guessing.
+7. Keep page switch/root components thin; move shared locale synchronization and context plumbing into composables or plugins when several embed pages need them.
+8. Prefer domain-specific frontend API helpers over one generic page-level `callAdminApi`; preserve status, field errors, and error codes in structured error objects.
+9. If a runtime error appears only in a minified bundle, switch to a dev bundle or sourcemaps before guessing.
 
 ## Page and menu checks
 
 - Published page descriptors must be objects, not string page codes.
 - Page descriptors need `code`, `menu`, and usually `menuItemTitle`.
+- Before choosing RetailCRM system `menu` or `parentMenuItemCode`, read `https://docs.retailcrm.ru/api/ru/RetailCRM/jsApiMethods/navigation`; do not guess menu codes from section names or stale examples.
 - Use `parentMenuItemCode` and `menuItemOrdering` to model the intended CRM page/menu hierarchy.
 - Breadcrumb-like navigation is derived by CRM from the page/menu hierarchy passed in the extension config; do not hand-roll breadcrumbs in the page unless the product task explicitly asks for local in-page navigation.
 - For updating an already installed module, use the existing integration module edit/update flow and put pages under `integrationModule.integrations.embedJs.pages`.
@@ -46,3 +49,10 @@ Use this skill before changing JS module endpoint wiring, page registration, wid
 - Use public Host API for location, query state, and navigation.
 - Do not depend on internal endpoint runtime stores or private channel state.
 - Keep route names, page codes, and extension descriptor values documented in the project.
+
+## Shared page setup checks
+
+- If i18n is used by several embed pages, synchronize remote locale once through a shared composable or plugin.
+- Do not duplicate the same locale watch/load code in every page component.
+- Domain helpers such as `loadSettings`, `saveSettings`, `loadSpecialties`, `saveSpecialist`, and `deleteSpecialist` should express page contracts better than generic transport calls.
+- If the API returns machine-readable error codes, translate them in the frontend UI layer; backend messages may be fallbacks or explicit product requirements, not the only structured contract.