@retailcrm/embed-ui-v1-endpoint 0.9.18 → 0.9.21

package/README.md

@@ -41,4 +41,6 @@ runEndpoint(runner)
 - [`createEndpoint`](./docs/create-endpoint.md) — как вручную создать endpoint с transport и messenger.
 - [`runEndpoint`](./docs/run-endpoint.md) — как поднять endpoint в worker entry одной строкой.
 - [`targets` и `defineTarget`](./docs/targets.md) — как типизировать цели виджетов и маршрутизировать их по target.
+- [`menu-placements`](./docs/menu-placements.md) — как описывать меню и пункты навигации для remote-страниц.
+- [`page-routes`](./docs/page-routes.md) — как связывать page `code`, CRM route и `definePageRunner`.
 - [`layout`](./docs/layout.md) — как выбирать layout-паттерны страниц, `modal sidebar` и `modal window`, и из каких `v1-components` их собирать.

package/docs/README.md

@@ -0,0 +1,18 @@
+# Документация `@retailcrm/embed-ui-v1-endpoint`
+
+В этом каталоге собраны продвинутые гайды по публичному API `v1-endpoint`.
+
+## По методам
+
+- [`defineRunner`](./define-runner.md) — объединение page/widget runners в один endpoint runner.
+- [`definePageRunner`](./define-page-runner.md) — запуск remote-страниц по `code`.
+- [`defineWidgetRunner`](./define-widget-runner.md) — запуск remote-виджетов по `target`.
+- [`createEndpoint`](./create-endpoint.md) — ручное создание endpoint с transport/messenger.
+- [`runEndpoint`](./run-endpoint.md) — запуск endpoint в worker одной строкой.
+
+## Дополнительно
+
+- [`targets` и `defineTarget`](./targets.md) — типизированные цели для виджетов.
+- [`menu-placements`](./menu-placements.md) — как описывать меню и пункты навигации, из которых открываются remote-страницы.
+- [`page-routes`](./page-routes.md) — как связывать page `code`, CRM route и `definePageRunner`.
+- [`layout`](./layout.md) — практический гайд по layout-паттернам страниц, шторок и модалок.

package/docs/create-endpoint.md

@@ -0,0 +1,54 @@
+# `createEndpoint`
+
+`createEndpoint` связывает runner и transport (messenger), после чего
+экспортирует endpoint API (`run`, `release`, `reset`) через `@remote-ui/rpc`.
+
+## Сигнатура
+
+```ts
+createEndpoint(
+  runner: {
+    page: PageRunner;
+    widget: WidgetRunner;
+  },
+  messenger: MessageEndpoint
+): Endpoint<RemoteApi>
+```
+
+## Что делает под капотом
+
+При `run(...)`:
+
+1. сбрасывает предыдущий mount для того же `id` (widget) или `code` (page),
+2. поднимает remote root (`mountEndpointRoot`),
+3. создаёт `pinia` и инжектит endpoint/context accessors,
+4. вызывает нужный runner (`page.run` или `widget.run`),
+5. сохраняет destroy-функцию в registry.
+
+При `release(...)`:
+
+- вызывает destroy для конкретного `id` или `code`.
+
+При `reset()`:
+
+- вызывает destroy для всех активных page/widget инстансов.
+
+## Пример (низкоуровневый)
+
+```ts
+import { defineRunner, createEndpoint } from '@retailcrm/embed-ui-v1-endpoint/remote'
+
+const runner = defineRunner({
+  pages: [MyPageRoot],
+  widgets: [MyWidgetRoot],
+})
+
+// messenger зависит от среды исполнения
+createEndpoint(runner, self as unknown as MessageEndpoint)
+```
+
+## Когда нужен именно `createEndpoint`
+
+- Нужна кастомная интеграция transport-слоя.
+- Вы сами контролируете, где и как создаётся `MessageEndpoint`.
+- Нужно использовать endpoint не через стандартный worker-entry сценарий.

package/docs/define-page-runner.md

@@ -0,0 +1,62 @@
+# `definePageRunner`
+
+`definePageRunner` создаёт runner для remote-страниц.
+При запуске в компонент пробрасывается проп `code`.
+
+## Перегрузки
+
+```ts
+definePageRunner(component: Component, beforeMount?: (app, pinia) => void | Promise<void>): Runner
+definePageRunner(runners: Record<string, Runner>): Runner
+```
+
+## Вариант 1. Один компонент на все `code`
+
+```ts
+import { definePageRunner } from '@retailcrm/embed-ui-v1-endpoint/remote'
+
+import PageRoot from './PageRoot.vue'
+
+const pageRunner = definePageRunner(PageRoot)
+```
+
+Компонент получит `code` как prop:
+
+```ts
+// внутри PageRoot
+defineProps<{
+  code: string;
+}>()
+```
+
+## Вариант 2. Разные раннеры по `code`
+
+```ts
+import { definePageRunner } from '@retailcrm/embed-ui-v1-endpoint/remote'
+
+import OrdersPage from './OrdersPage.vue'
+import CustomersPage from './CustomersPage.vue'
+
+const pageRunner = definePageRunner({
+  orders: definePageRunner(OrdersPage),
+  customers: definePageRunner(CustomersPage),
+})
+```
+
+Если для `code` нет раннера, будет warning в консоль и noop-destroy.
+
+## `beforeMount`
+
+`beforeMount` вызывается после `app.use(pinia)` и до `app.mount(...)`.
+Подходит для регистрации плагинов, глобальных компонентов и начальной синхронизации сторов.
+
+```ts
+const pageRunner = definePageRunner(PageRoot, async (app, pinia) => {
+  // init code
+})
+```
+
+Читайте также:
+
+- [`page-routes`](./page-routes.md) — как связать page `code`, CRM route и компонент страницы.
+- [`menu-placements`](./menu-placements.md) — как описывать пункты меню, которые открывают remote-страницы.

package/docs/define-runner.md

@@ -0,0 +1,63 @@
+# `defineRunner`
+
+`defineRunner` — это фасад над `definePageRunner` и `defineWidgetRunner`.
+Он создаёт единый runner для endpoint, который умеет запускать и страницы, и виджеты.
+
+## Сигнатура
+
+```ts
+defineRunner(config: {
+  pages: Parameters<typeof definePageRunner>;
+  widgets: Parameters<typeof defineWidgetRunner>;
+}): {
+  page: PageRunner;
+  widget: WidgetRunner;
+}
+```
+
+## Когда использовать
+
+- Когда в одной интеграции есть и page-, и widget-сценарии.
+- Когда нужен единый объект для `createEndpoint(...)` или `runEndpoint(...)`.
+
+## Пример
+
+```ts
+import { defineRunner } from '@retailcrm/embed-ui-v1-endpoint/remote'
+
+import OrdersPage from './pages/OrdersPage.vue'
+import OrderCommonWidget from './widgets/OrderCommonWidget.vue'
+
+const runner = defineRunner({
+  pages: [OrdersPage],
+  widgets: [OrderCommonWidget],
+})
+```
+
+## Пример с beforeMount и маппингом
+
+```ts
+import { definePageRunner, defineRunner, defineWidgetRunner } from '@retailcrm/embed-ui-v1-endpoint/remote'
+
+import OrdersPage from './pages/OrdersPage.vue'
+import CustomersPage from './pages/CustomersPage.vue'
+import CommonBeforeWidget from './widgets/CommonBeforeWidget.vue'
+import CommonAfterWidget from './widgets/CommonAfterWidget.vue'
+
+const runner = defineRunner({
+  pages: [{
+    orders: definePageRunner(OrdersPage),
+    customers: definePageRunner(CustomersPage),
+  }],
+
+  widgets: [{
+    'order/card:common.before': defineWidgetRunner(CommonBeforeWidget),
+    'order/card:common.after': defineWidgetRunner(CommonAfterWidget),
+  }],
+})
+```
+
+## Что важно помнить
+
+- `pages` и `widgets` передаются как tuple-аргументы соответствующих методов.
+- Если нужен полный контроль над каждым типом runner, можно использовать `definePageRunner` и `defineWidgetRunner` напрямую.

package/docs/define-widget-runner.md

@@ -0,0 +1,56 @@
+# `defineWidgetRunner`
+
+`defineWidgetRunner` создаёт runner для remote-виджетов.
+При запуске в компонент пробрасывается проп `target`.
+
+## Перегрузки
+
+```ts
+defineWidgetRunner(component: Component, beforeMount?: (app, pinia) => void | Promise<void>): Runner
+defineWidgetRunner(runners: Partial<Record<TargetName, Runner>>): Runner
+```
+
+## Вариант 1. Один компонент на все target
+
+```ts
+import { defineWidgetRunner } from '@retailcrm/embed-ui-v1-endpoint/remote'
+
+import WidgetRoot from './WidgetRoot.vue'
+
+const widgetRunner = defineWidgetRunner(WidgetRoot)
+```
+
+Компонент получит `target` как prop:
+
+```ts
+// внутри WidgetRoot
+defineProps<{
+  target: string;
+}>()
+```
+
+## Вариант 2. Разные раннеры по `target`
+
+```ts
+import { defineWidgetRunner } from '@retailcrm/embed-ui-v1-endpoint/remote'
+
+import BeforeWidget from './BeforeWidget.vue'
+import AfterWidget from './AfterWidget.vue'
+
+const widgetRunner = defineWidgetRunner({
+  'order/card:common.before': defineWidgetRunner(BeforeWidget),
+  'order/card:common.after': defineWidgetRunner(AfterWidget),
+})
+```
+
+Если для `target` нет раннера, будет warning в консоль и noop-destroy.
+
+## `beforeMount`
+
+`beforeMount` работает аналогично page-раннеру: выполняется перед mount и после подключения `pinia`.
+
+```ts
+const widgetRunner = defineWidgetRunner(WidgetRoot, async (app, pinia) => {
+  // init code
+})
+```

package/docs/layout.md

@@ -0,0 +1,363 @@
+# Гайд по layout для страниц и связанных экранов
+
+Этот документ собирает в одном месте практические правила по тому, как проектировать
+страницы для `@retailcrm/embed-ui-v1-endpoint`: списки, карточки, страницы с несколькими
+колонками, страницы с collapse-блоками, а также случаи, когда вместо полноценной страницы
+следует использовать `modal sidebar` или `modal window`.
+
+Это не API-справка по `v1-endpoint`, а UX/layout guide для людей, которые собирают remote-page
+через `definePageRunner(...)` и хотят держаться общего визуального языка CRM.
+
+## Базовая ментальная модель
+
+Обычная страница в CRM чаще всего состоит из таких зон:
+
+1. Заголовок страницы.
+2. Справа от заголовка: primary и вспомогательные действия.
+3. Опционально: фильтры или tabs под заголовком.
+4. Основной контент на белых подложках.
+5. Опционально: нижняя панель сохранения.
+
+Если экран перестаёт быть удобной полноценной страницей, его не следует усложнять бесконечно;
+в этом случае его следует переводить в другой паттерн: `modal sidebar` или `modal window`.
+
+## Термины
+
+В этом документе используются следующие термины:
+
+- `modal sidebar` — боковая выезжающая панель. В разговорной речи может называться “шторкой”.
+- `modal window` — всплывающее модальное окно. В разговорной речи может называться “модалкой”.
+- `страница` — основной route-level экран, который занимает центральную рабочую область CRM.
+
+Далее по тексту предпочтительно используются термины `modal sidebar` и `modal window`, потому что
+они напрямую соотносятся с компонентами `UiModalSidebar`, `UiModalWindow` и `UiModalWindowSurface`.
+
+## Общие правила
+
+### Отступы и сетка
+
+- Базовая система расстояний строится на шаге `4px`.
+- Используйте расстояния, кратные `4px`: `4`, `8`, `12`, `16`, `20`, `24`, `28`, `32`.
+- Для контентных подложек базовое правило такое:
+  - отступ от верхнего края подложки: `24px`;
+  - отступы от левого, правого и нижнего края: `32px`.
+- Между смысловыми блоками оставляйте заметную дистанцию, а не склеивайте их.
+
+### Заголовок страницы
+
+- Заголовок страницы обычно строится на `Text large Accent 24`.
+- Заголовок может быть статическим или редактируемым inline.
+- Справа от заголовка может быть одна или несколько кнопок.
+- Рядом с кнопками может жить дополнительный текстовый статус или небольшая вспомогательная ссылка.
+
+Типичная компонентная основа:
+
+- `UiPageHeader` для верхнего блока страницы.
+- `UiButton`, `UiToolbarButton`, `UiToolbarLink` для действий справа от заголовка.
+
+### Кнопки
+
+- На странице допускается одна основная `Default Primary` кнопка.
+- Отдельно может быть одна `Success Primary`, если сценарий этого требует.
+- Остальные действия рекомендуется оформлять через `Default Secondary`, `Default Tertiary`, `Success Secondary` и похожие менее доминирующие варианты.
+- Если действий много, одно оставляют главным, а остальные уводят во вторичный слой или dropdown.
+
+Типичная компонентная основа:
+
+- `UiButton` для primary, secondary и tertiary действий.
+- `UiMenuItem` и `UiPopper` для вторичных выпадающих меню, если действий слишком много для строки заголовка.
+
+### Подложки
+
+- Основной контент страницы обычно расположен на белых подложках.
+- Подложка должна собирать один смысловой блок, а не случайный набор элементов.
+- Если на экране есть несколько независимых смысловых секций, предпочтительнее использовать несколько подложек, чем одну перегруженную.
+
+## 1. Страница со списком сущностей
+
+### Когда использовать
+
+- Списки заказов.
+- Списки клиентов.
+- Списки рассылок.
+- Списки задач.
+- Любые индексные страницы, где важны поиск, фильтрация и массовый просмотр данных.
+
+### Из чего обычно состоит
+
+1. Заголовок страницы.
+2. Одна или несколько кнопок справа от заголовка.
+3. Блок фильтров.
+4. Таблица со списком сущностей.
+5. Пагинация и сопутствующие действия таблицы.
+
+### Структура блока фильтров
+
+- Фильтры собираются из полей вроде `Select`, `Input`, `Combo-box`, date-range и других компактных контролов.
+- Под блоком фильтров обычно есть кнопка применения и отдельная кнопка сброса.
+- Фильтры удобно располагать в ряды примерно по `4-5` штук.
+- Если фильтров больше, они переходят на следующую строку.
+- Фильтры допускается сворачивать, если экран ими перегружается.
+
+Типичная компонентная основа:
+
+- `UiField` как обертка для подписи, hint и validation state.
+- `UiTextbox`, `UiSelect`, `UiDatePicker`, `UiTimePicker`, `UiCheckbox`, `UiRadioSwitch` как фильтрующие контролы.
+- `UiButton` для действий `Применить`, `Сбросить`, `Очистить`.
+
+### Роль таблицы
+
+- Таблица является главным содержимым списка.
+- Она может листаться, пагинироваться и поддерживать выгрузку.
+- Не следует смешивать в одном списочном экране слишком много “карточной” логики; список должен оставаться в первую очередь инструментом поиска и просмотра.
+
+Типичная компонентная основа:
+
+- `UiTable` как корневой компонент списка.
+- `UiTableColumn`, `UiTableHeadCell`, `UiTableBodyCell`, `UiTableSorter`, `UiTableFooterSection`, `UiTableFooterButton` как составные части таблицы.
+
+## 2. Страница-карточка
+
+### Когда использовать
+
+- Страница настроек.
+- Карточка сущности.
+- Экран редактирования одной логической сущности.
+
+### Из чего обычно состоит
+
+1. Заголовок страницы, иногда редактируемый inline.
+2. Справа: основные действия.
+3. Опционально: tabs под заголовком.
+4. Одна или несколько подложек с контентом.
+5. Опционально: нижняя панель сохранения.
+
+### Типичный состав
+
+- Текстовые блоки.
+- Кнопки и ссылки.
+- Поля формы.
+- `Checkbox` и `Radio`.
+- `Switch`.
+- Небольшие встроенные таблицы.
+
+Типичная компонентная основа:
+
+- `UiField`, `UiTextbox`, `UiSelect`, `UiCheckbox`, `UiRadio`, `UiSwitch`, `UiRadioSwitch` для формы.
+- `UiButton` и `UiLink` для действий внутри карточки.
+- `UiTable` для компактных встроенных списков.
+
+### Когда нужны tabs
+
+- Когда одна карточка делится на несколько крупных разделов.
+- Когда переключение между разделами должно происходить без ухода на другой экран.
+- Tabs рекомендуется использовать как верхнеуровневую навигацию по смысловым секциям, а не как замену каждому внутреннему блоку.
+
+Типичная компонентная основа:
+
+- `UiTabGroup` для управления активным разделом.
+- `UiTab` для декларации вкладок, иконок, счетчиков и содержимого активной панели.
+
+### Когда нужна панель сохранения
+
+- Когда на странице много редактируемых полей и важно явно отделить действия `Сохранить`, `Сохранить и выйти`, `Закрыть`, `Удалить`.
+- Если каждый блок сохраняется отдельно, глобальная нижняя панель обычно не нужна.
+
+Типичная компонентная основа:
+
+- `UiButton` для основных действий в нижней панели.
+- `UiToolbarButton` и `UiToolbarLink` для вторичных действий, если они должны выглядеть менее тяжело.
+
+## 2.1. Страница с несколькими колонками
+
+Это частный случай страницы-карточки, когда контент логично раскладывается не только по вертикали, но и по горизонтали.
+
+### Когда использовать
+
+- Карточка заказа.
+- Карточка клиента.
+- Страница просмотра товара.
+- Любой экран, где рядом должны жить несколько смысловых секций.
+
+### Правила раскладки
+
+- Контент всё равно живёт на подложках.
+- Между соседними блоками держите примерно `24px`.
+- Типовые раскладки колонок:
+  - `100%`;
+  - `50% / 50%`;
+  - `30% / 70%`.
+
+Типичная компонентная основа:
+
+- обычные form/content blocks на базе `UiField`, `UiTextbox`, `UiSelect`, `UiCheckbox`, `UiSwitch`;
+- при необходимости небольшие встроенные `UiTable`;
+- tabs по-прежнему остаются верхним уровнем и не заменяют сетку колонок.
+
+### Когда это уместно
+
+- Когда блоки действительно связаны и их необходимо видеть рядом.
+- Когда экран выигрывает от сравнения двух секций одновременно.
+
+### Признаки неудачной раскладки
+
+- Если одна из колонок становится слишком длинной, а вторая остаётся почти пустой.
+- Если блоки начинают требовать собственную внутреннюю сложную навигацию.
+
+## 3. Страница с collapse-блоками
+
+### Когда использовать
+
+- Настройки, разбитые на смысловые группы.
+- Большие формы, где не всё нужно держать открытым одновременно.
+- Редактирование товара, рассылки и похожих сущностей с независимыми секциями.
+
+### Особенности
+
+- Если на странице используются `Collapse`-блоки, дополнительная общая белая подложка вокруг них обычно не нужна.
+- Если подложка видна только ради пары collapse-блоков, от неё следует отказаться.
+- Обычно и общая нижняя панель сохранения не нужна, потому что каждый блок сохраняется отдельно.
+
+### Типичный состав
+
+- Текст.
+- Кнопки.
+- Поля и контролы.
+- Небольшие таблицы.
+
+Типичная компонентная основа:
+
+- `UiCollapseBox` и `UiCollapseGroup` для секций.
+- Внутри секции: `UiField`, `UiTextbox`, `UiSelect`, `UiCheckbox`, `UiRadio`, `UiSwitch`, `UiButton`.
+- При необходимости: компактные `UiTable`.
+
+### Ограничения
+
+- Сложные большие таблицы.
+- Другие collapse-блоки.
+- Контент, разнесённый на две колонки по разным подложкам.
+
+## 4. Когда вместо страницы нужен `modal sidebar`
+
+### Когда использовать
+
+- Небольшая форма “по месту”.
+- Карточка маленькой сущности с ограниченным числом полей.
+- Дополнительная информация, которую не хочется разворачивать в отдельную страницу.
+- Сценарии вроде задач, уведомлений, нового обращения, редактирования шага.
+
+### Размеры
+
+- Часто используется одна из двух ширин: `720px` или `416px`.
+
+### Основные части
+
+1. Закреплённый `header`.
+2. Прокручиваемый контент.
+3. Закреплённый `footer`.
+
+Типичная компонентная основа:
+
+- `UiModalSidebar` как контейнер `modal sidebar`.
+- Внутри: обычные form/content primitives из `v1-components`.
+- В `footer`: `UiButton` для сохранения, закрытия и удаления.
+
+### Типичный состав
+
+- Формы.
+- Небольшие карточки.
+- Небольшие таблицы.
+- Вспомогательный текст.
+
+### Ограничения
+
+- `Collapse`-блоки.
+- Контент в двух колонках на разных подложках.
+- Громоздкие, большие и сложные интерфейсы.
+
+Если экран фактически превращается в полноценную страницу или большую предметную область, `modal sidebar` уже не является подходящим выбором.
+
+## 5. Когда вместо страницы нужен `modal window`
+
+### Когда использовать
+
+- Для отображения большой вспомогательной таблицы “по месту”.
+- Для дополнительных настроек, когда `modal sidebar` уже не хватает.
+- Для сценариев просмотра или выбора, не заслуживающих отдельного route-level экрана.
+
+### Размеры
+
+- Обычный `modal window` шириной около `960px`.
+- Или полноэкранный режим с внешними отступами по краям.
+
+### Основные части
+
+1. Закреплённый `header`.
+2. Основной контент.
+3. Закреплённый `footer`.
+
+Типичная компонентная основа:
+
+- `UiModalWindow` и `UiModalWindowSurface` как базовый контейнер модального сценария.
+- Внутри: `UiTable`, `UiField`, `UiTextbox`, `UiSelect`, `UiButton`, а при необходимости `UiTabGroup`.
+
+### Практические правила
+
+- В целом контент в `modal window` может быть любым, но чаще всего там живут таблицы и компактные формы.
+- Если в `modal window` есть таблица, её обычно растягивают на всю ширину окна.
+- Если `modal window` делится на крупные разделы, вместо усложнённого header рекомендуется использовать большие tabs.
+
+## Выбор паттерна
+
+### Полноценная страница подходит, если
+
+- сценарий является самостоятельным рабочим экраном;
+- у экрана есть собственная навигационная ценность;
+- контента много, и ему нужен нормальный вертикальный ритм;
+- ожидается несколько крупных смысловых секций.
+
+### `Modal sidebar` подходит, если
+
+- это быстрый побочный сценарий;
+- форма маленькая или средняя;
+- пользователь должен остаться в контексте текущего экрана.
+
+### `Modal window` подходит, если
+
+- требуется показать большой вспомогательный контент по месту;
+- требуется быстро завершить отдельный шаг без перехода на полноценную страницу;
+- `modal sidebar` уже тесен, но полноценная страница всё ещё избыточна.
+
+## Сопоставление с `embed-ui`
+
+Ниже не жёсткий contract, а практичное соответствие layout-паттернов библиотечным примитивам:
+
+- заголовок страницы: `UiPageHeader`;
+- верхние actions: `UiButton`, `UiToolbarButton`, `UiToolbarLink`;
+- tabs: `UiTabGroup` и `UiTab`;
+- collapse-группы: `UiCollapseBox`, `UiCollapseGroup`;
+- фильтры и формы: `UiField`, `UiTextbox`, `UiSelect`, `UiCheckbox`, `UiRadio`, `UiSwitch`, `UiRadioSwitch`;
+- таблицы: `UiTable` и связанные table primitives;
+- `modal sidebar`: `UiModalSidebar`;
+- `modal window`: `UiModalWindow` и `UiModalWindowSurface`.
+
+## Чеклист перед реализацией страницы
+
+Перед тем как собирать новый page runner, полезно ответить на несколько вопросов:
+
+1. Это действительно страница, а не `modal sidebar` и не `modal window`?
+2. Это список, карточка, карточка с колонками или collapse-настройки?
+3. Нужны ли tabs, или блоки следует оставить на одном полотне?
+4. Нужна ли общая панель сохранения, или каждый блок должен сохраняться отдельно?
+5. Не перегружен ли экран количеством primary-действий?
+6. Держатся ли отступы и расстояния сетки `4px`?
+
+Если на эти вопросы нет уверенного ответа, сначала следует выбрать подходящий layout-паттерн,
+а уже потом собирать компоненты и wiring через `v1-endpoint`.
+
+---
+
+Примечание: все упоминаемые в этом документе компоненты вида `Ui*` относятся к пакету
+`@retailcrm/embed-ui-v1-components`. Термины `modal sidebar`, `modal window`, tabs, collapse-группы,
+таблицы, поля и другие layout-примитивы в этом гайде привязаны именно к публичным компонентам
+из `v1-components`, а не к произвольной внутренней терминологии проекта.

package/docs/menu-placements.md

@@ -0,0 +1,71 @@
+# Меню и точки входа страниц
+
+Этот справочник описывает, как документировать меню и пункты навигации, из которых запускаются
+remote-страницы расширения.
+
+Важно: `v1-endpoint` не экспортирует типизированный registry CRM-меню. Пакет отвечает за запуск
+страницы по `code`, а список меню, подпунктов и их видимость задаются на стороне host/manifest
+конкретного расширения.
+
+## Термины
+
+- `menu placement` — зона CRM, куда host добавляет пункт навигации.
+- `menu item` — конкретный пункт меню, который видит пользователь.
+- `page code` — стабильный код remote-страницы, который host передаёт в `definePageRunner`.
+- `route` — маршрут CRM или route name, через который host открывает страницу.
+
+`menu item` не равен `target`. Меню открывает полноценную remote-страницу по `code`, а `target`
+используется для виджетов, которые встраиваются внутрь уже существующей CRM-страницы.
+
+## Что нужно фиксировать в справочнике проекта
+
+Для каждого пункта меню указывайте:
+
+| Поле | Что означает |
+| --- | --- |
+| `placement` | Зона CRM, где находится пункт меню. |
+| `item code` | Стабильный код пункта меню в host/manifest. |
+| `label` | Пользовательское название пункта меню. |
+| `page code` | Код remote-страницы, который получит `definePageRunner`. |
+| `route` | Имя или путь CRM-маршрута, если пункт открывается через host routing. |
+| `visibility` | Условия показа: права, настройки, тариф, доступность фичи. |
+
+## Пример справочника меню
+
+Это пример формата. Конкретные `placement`, `item code` и `route` нужно брать из host/manifest
+расширения.
+
+| Placement | Item code | Label | Page code | Route | Когда использовать |
+| --- | --- | --- | --- | --- | --- |
+| `main` | `orders-dashboard` | Заказы | `orders-dashboard` | `embed.page.orders_dashboard` | Основной пункт навигации расширения. |
+| `settings` | `integration-settings` | Настройки интеграции | `integration-settings` | `embed.page.integration_settings` | Страница настроек, доступная администраторам. |
+| `customer/card:actions` | `customer-tools` | Инструменты клиента | `customer-tools` | `embed.page.customer_tools` | Пункт в контексте карточки клиента. |
+
+## Связь с `definePageRunner`
+
+`page code` из справочника меню должен совпадать с ключом runner:
+
+```ts
+import { definePageRunner } from '@retailcrm/embed-ui-v1-endpoint/remote'
+
+import CustomerToolsPage from './pages/CustomerToolsPage.vue'
+import IntegrationSettingsPage from './pages/IntegrationSettingsPage.vue'
+import OrdersDashboardPage from './pages/OrdersDashboardPage.vue'
+
+const pageRunner = definePageRunner({
+  'customer-tools': definePageRunner(CustomerToolsPage),
+  'integration-settings': definePageRunner(IntegrationSettingsPage),
+  'orders-dashboard': definePageRunner(OrdersDashboardPage),
+})
+```
+
+Если host откроет страницу с `code`, которого нет в runner map, `definePageRunner` запишет warning
+в консоль и не смонтирует страницу.
+
+Читайте также:
+
+- [`page-routes`](./page-routes.md) — как описывать page `code` и CRM route.
+- [`definePageRunner`](./define-page-runner.md) — как remote-страница получает `code`.
+- [`targets`](./targets.md) — точки встраивания виджетов, не пунктов меню.
+- [`layout`](./layout.md) — когда делать полноценную страницу, а когда `modal sidebar` или `modal window`.
+- [`UiMenuItem`](../../v1-components/docs/profiles/UiMenuItem.yml) — компонент строки меню внутри UI расширения.

package/docs/page-routes.md

@@ -0,0 +1,82 @@
+# Роуты страниц
+
+Remote-страницы в `v1-endpoint` запускаются по `code`. Этот `code` приходит от host и пробрасывается
+в компонент через `definePageRunner`.
+
+`v1-endpoint` не задаёт фиксированный список page routes. Список страниц и CRM-маршрутов принадлежит
+host/manifest конкретного расширения, поэтому его нужно хранить в справочнике проекта рядом с кодом
+расширения.
+
+## Что такое `page code`
+
+`page code` — стабильный идентификатор remote-страницы внутри расширения. Он отвечает на вопрос:
+«какую страницу расширения нужно смонтировать?».
+
+Пример:
+
+```ts
+import { definePageRunner } from '@retailcrm/embed-ui-v1-endpoint/remote'
+
+import OrdersDashboardPage from './pages/OrdersDashboardPage.vue'
+
+const pageRunner = definePageRunner({
+  'orders-dashboard': definePageRunner(OrdersDashboardPage),
+})
+```
+
+Когда host запускает страницу с `code: 'orders-dashboard'`, компонент `OrdersDashboardPage` получает
+этот код как prop:
+
+```vue
+<script setup lang="ts">
+defineProps<{
+  code: string;
+}>()
+</script>
+```
+
+## Что такое `route`
+
+`route` — CRM-маршрут или route name, через который host открывает страницу. В remote-коде route
+может использоваться для переходов через `HostApi.goTo(route, params)`.
+
+Данные Symfony JS router доступны в контексте `settings` в поле `system.routing`. Это полезно,
+когда нужно проверить доступные route names или собрать ссылку тем же routing data, что отдаёт host.
+
+```ts
+import { useContext as useSettingsContext } from '@retailcrm/embed-ui-v1-contexts/remote/settings'
+
+const settings = useSettingsContext()
+
+console.log(settings['system.routing'].routes)
+```
+
+## Пример справочника роутов страниц
+
+Это пример формата. Конкретные `code`, `route` и параметры нужно брать из host/manifest расширения.
+
+| Page code | Route | Params | Открывается из | Компонент |
+| --- | --- | --- | --- | --- |
+| `orders-dashboard` | `embed.page.orders_dashboard` | `{}` | `main / orders-dashboard` | `OrdersDashboardPage.vue` |
+| `integration-settings` | `embed.page.integration_settings` | `{}` | `settings / integration-settings` | `IntegrationSettingsPage.vue` |
+| `customer-tools` | `embed.page.customer_tools` | `{ customerId }` | `customer/card:actions / customer-tools` | `CustomerToolsPage.vue` |
+
+## Переход на CRM route
+
+Если странице нужен переход на другой CRM-маршрут, используйте host API, а не прямую сборку URL.
+Способ получения `HostApi` зависит от host-интеграции проекта, но сам публичный контракт выглядит так:
+
+```ts
+import type { HostApi } from '@retailcrm/embed-ui-v1-types/host'
+
+const openSettings = (host: HostApi) => {
+  host.goTo('embed.page.integration_settings')
+}
+```
+
+Читайте также:
+
+- [`menu-placements`](./menu-placements.md) — как связать пункт меню, page `code` и route.
+- [`definePageRunner`](./define-page-runner.md) — как page `code` попадает в компонент.
+- [`settings context`](../../v1-contexts/docs/ru/CONCEPT.md) — общий принцип работы контекстов.
+- [`HostApi`](../../v1-types/host.d.ts) — публичный тип host API с `goTo`.

package/docs/run-endpoint.md

@@ -0,0 +1,37 @@
+# `runEndpoint`
+
+`runEndpoint` — shortcut для worker entry:
+он вызывает `createEndpoint(runner, self as Worker)`.
+
+## Сигнатура
+
+```ts
+runEndpoint(runner: Runner): Endpoint<RemoteApi>
+```
+
+## Базовый сценарий
+
+```ts
+// endpoint.worker.ts
+import { defineRunner, runEndpoint } from '@retailcrm/embed-ui-v1-endpoint/remote'
+
+import OrdersPage from './pages/OrdersPage.vue'
+import OrderWidget from './widgets/OrderWidget.vue'
+
+const runner = defineRunner({
+  pages: [OrdersPage],
+  widgets: [OrderWidget],
+})
+
+runEndpoint(runner)
+```
+
+## Когда использовать
+
+- Почти всегда, если endpoint запускается как web worker.
+- Когда не нужен ручной контроль над messenger/transport.
+
+## Когда лучше `createEndpoint`
+
+- Когда transport создаётся не от `self` worker.
+- Когда у вас кастомный runtime/bridge между host и remote.

package/docs/targets.md

@@ -0,0 +1,111 @@
+# `targets` и `defineTarget`
+
+Модуль `@retailcrm/embed-ui-v1-endpoint/common` содержит
+типизированные target-идентификаторы и helper для объявления целей.
+
+## Что экспортируется
+
+- `targets` — словарь встроенных target-конфигураций.
+- `TargetName` — union всех ключей `targets`.
+- `defineTarget(id, contexts)` — helper для объявления target с типами контекстов.
+
+## Что такое `target` и `context`
+
+`target` — это идентификатор места встраивания виджета в интерфейсе CRM. Он отвечает на вопрос:
+«куда CRM сейчас монтирует remote-виджет?». Например, `order/card:common.before` означает конкретную
+точку встраивания на карточке заказа.
+
+`context` — это набор реактивных данных, доступных виджету в этом месте. Он отвечает на вопрос:
+«какие данные CRM можно читать или менять из этого виджета?». Список контекстов задаётся в
+`targets[target].contexts`.
+
+`target` не является данными заказа, клиента или пользователя. Это только место встраивания.
+Данные нужно брать из контекстов, которые привязаны к этому `target`.
+
+## Примеры встроенных `target`
+
+| Target | Где встраивается | Доступные контексты |
+| --- | --- | --- |
+| `order/card:common.before` | Карточка заказа, перед блоком общей информации | `order/card`, `user/current`, `settings` |
+| `order/card:customer.phone` | Карточка заказа, поле телефона клиента | `order/card`, `user/current`, `settings` |
+| `customer/card:phone` | Карточка клиента, телефонный блок | `customer/card`, `customer/card:phone`, `user/current`, `settings` |
+| `order/mg:list.before` | Карточка заказа, перед списком в multi-goods блоке | `order/card`, `order/card:settings`, `user/current`, `settings` |
+
+## Проверка контекстов для `target`
+
+```ts
+import { targets } from '@retailcrm/embed-ui-v1-endpoint/common'
+
+const target = targets['customer/card:phone']
+
+console.log(target.contexts)
+// ['customer/card', 'customer/card:phone', 'user/current', 'settings']
+```
+
+Если виджет монтируется в `customer/card:phone`, можно использовать контексты клиента, телефонного
+блока, текущего пользователя и настроек. Контексты заказа в этой точке встраивания использовать не нужно.
+
+## Пример использования `TargetName`
+
+```ts
+import type { TargetName } from '@retailcrm/embed-ui-v1-endpoint/common'
+
+const selectedTarget: TargetName = 'order/card:common.before'
+```
+
+## Пример виджета с `target` и контекстами
+
+```vue
+<script setup lang="ts">
+import type { TargetName } from '@retailcrm/embed-ui-v1-endpoint/common'
+
+import { useContext as useOrderContext } from '@retailcrm/embed-ui-v1-contexts/remote/order/card'
+import { useContext as useSettingsContext } from '@retailcrm/embed-ui-v1-contexts/remote/settings'
+import { useContext as useUserContext } from '@retailcrm/embed-ui-v1-contexts/remote/user/current'
+
+defineProps<{
+  target: TargetName;
+}>()
+
+const order = useOrderContext()
+const settings = useSettingsContext()
+const user = useUserContext()
+</script>
+```
+
+Такой набор контекстов подходит для `order/card:common.before`, потому что этот `target` объявлен с
+контекстами `order/card`, `user/current` и `settings`.
+
+Для `customer/card:phone` набор импортов будет другим:
+
+```ts
+import { useContext as useCustomerContext } from '@retailcrm/embed-ui-v1-contexts/remote/customer/card'
+import { useContext as usePhoneContext } from '@retailcrm/embed-ui-v1-contexts/remote/customer/card-phone'
+import { useContext as useSettingsContext } from '@retailcrm/embed-ui-v1-contexts/remote/settings'
+import { useContext as useUserContext } from '@retailcrm/embed-ui-v1-contexts/remote/user/current'
+```
+
+## Пример `defineTarget`
+
+```ts
+import { defineTarget } from '@retailcrm/embed-ui-v1-endpoint/common'
+
+const customTarget = defineTarget('order/card:custom.after', [
+  'order/card',
+  'user/current',
+  'settings',
+] as const)
+```
+
+## Практический совет
+
+Если раннер маппится по `target`, старайтесь использовать ключи из `TargetName`.
+Это снижает риск опечаток и помогает IDE/TS сразу показать несовместимые значения.
+
+Читайте также:
+
+- [`defineWidgetRunner`](./define-widget-runner.md) — как `target` попадает в remote-компонент.
+- [`menu-placements`](./menu-placements.md) — чем пункты меню для страниц отличаются от widget `target`.
+- [`page-routes`](./page-routes.md) — как описывать page `code` и CRM route.
+- [`CONCEPT`](../../v1-contexts/docs/ru/CONCEPT.md) — общий принцип работы контекстов.
+- [`CUSTOM`](../../v1-contexts/docs/ru/CUSTOM.md) — пользовательский контекст для custom fields.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@retailcrm/embed-ui-v1-endpoint",
   "type": "module",
-  "version": "0.9.18",
+  "version": "0.9.21",
   "description": "Endpoint API for integrations in RetailCRM",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
@@ -67,6 +67,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
   "scripts": {
@@ -78,27 +79,27 @@
   },
   "peerDependencies": {
     "@remote-ui/rpc": "^1.4",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.18",
-    "@retailcrm/embed-ui-v1-types": "^0.9.18",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.21",
+    "@retailcrm/embed-ui-v1-types": "^0.9.21",
     "pinia": "^2.2",
     "vue": "^3.5"
   },
   "dependencies": {
     "@remote-ui/rpc": "^1.4.7",
-    "@retailcrm/embed-ui-v1-components": "^0.9.18",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.18",
-    "@retailcrm/embed-ui-v1-types": "^0.9.18"
+    "@retailcrm/embed-ui-v1-components": "^0.9.21",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.21",
+    "@retailcrm/embed-ui-v1-types": "^0.9.21"
   },
   "devDependencies": {
     "@retailcrm/image-preview": "^1.0.2",
-    "@vitest/browser": "4.0.15",
-    "@vitest/browser-playwright": "4.0.15",
+    "@vitest/browser": "4.1.3",
+    "@vitest/browser-playwright": "4.1.3",
     "date-fns": "^4.1.0",
     "lodash.isequal": "^4.5.0",
     "playwright": "1.58.2",
-    "vite": "^7.2.7",
+    "vite": "^7.3.2",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "4.0.15"
+    "vitest": "4.1.3"
   },
   "publishConfig": {
     "access": "public"