@retailcrm/embed-ui-v1-contexts 0.9.23-alpha.2 → 0.9.23

package/docs/contexts/settings.yml

@@ -0,0 +1,54 @@
+"context": "settings"
+"summary": "Readonly CRM settings context with UI locale, Symfony router data, and image preview worker hosts."
+"language": "en-GB"
+"audience": "ai"
+"public_import":
+  "usage_import": "import { useContext } from '@retailcrm/embed-ui-v1-contexts/remote/settings'"
+  "usage_call": "const settings = useContext()"
+"fields":
+  -
+    "name": "image.workers"
+    "type": "Array<string>"
+    "readonly": true
+    "description": "List of image preview worker hosts used to build resized or cropped image URLs."
+    "source_of_truth": "List of image preview worker hosts used to build resized or cropped image URLs."
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes":
+      - "Pass these workers to usePreview or @retailcrm/image-preview preview()."
+      - "If the list is empty, preview helpers return the original image URL."
+      - "Workers are used for image preview resizing and cropping, not for uploading or storing images."
+  -
+    "name": "system.locale"
+    "type": "\"en-GB\"|\"es-ES\"|\"ru-RU\""
+    "readonly": true
+    "description": "Current system's locale"
+    "source_of_truth": "Current CRM UI locale for the opened account session."
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes":
+      - "Use this locale for extension UI localization."
+  -
+    "name": "system.routing"
+    "type": "RoutingData"
+    "readonly": true
+    "description": "Data for Symfony's JS router"
+    "source_of_truth": "Symfony router dump for CRM routes available to the extension."
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes":
+      - "Use this Symfony router data to build CRM route URLs."
+      - "Pass the routing data to @omnicajs/symfony-router instead of concatenating CRM URLs manually."
+"field_groups": []
+"types": []
+"usage":
+  "import": "import { useContext } from '@retailcrm/embed-ui-v1-contexts/remote/settings'"
+  "call": "const settings = useContext()"
+"related_actions": []
+"ai_notes": []

package/docs/contexts/user-current.yml

@@ -0,0 +1,119 @@
+"context": "user/current"
+"summary": "Readonly current user context with identity, groups, permissions and quick role flags."
+"language": "en-GB"
+"audience": "ai"
+"public_import":
+  "usage_import": "import { useContext } from '@retailcrm/embed-ui-v1-contexts/remote/user/current'"
+  "usage_call": "const user = useContext()"
+"fields":
+  -
+    "name": "id"
+    "type": "number|null"
+    "readonly": true
+    "description": "User ID"
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes": []
+  -
+    "name": "email"
+    "type": "string"
+    "readonly": true
+    "description": "User email"
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes": []
+  -
+    "name": "firstName"
+    "type": "string|null"
+    "readonly": true
+    "description": "User name"
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes": []
+  -
+    "name": "lastName"
+    "type": "string|null"
+    "readonly": true
+    "description": "User last name"
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes": []
+  -
+    "name": "patronymic"
+    "type": "string|null"
+    "readonly": true
+    "description": "Patronymic of the user"
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes": []
+  -
+    "name": "photo"
+    "type": "string|null"
+    "readonly": true
+    "description": "User photo"
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes": []
+  -
+    "name": "groups"
+    "type": "Array<string>"
+    "readonly": true
+    "description": "Symbolic codes of the groups the user belongs to"
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes":
+      - "Use group codes for role/group-based UI decisions."
+  -
+    "name": "permissions"
+    "type": "Array<string>"
+    "readonly": true
+    "description": "Character codes of available user permissions"
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes":
+      - "Use permission codes for feature gating and conditional action visibility."
+  -
+    "name": "isAdmin"
+    "type": "boolean"
+    "readonly": true
+    "description": "Indicates whether the user has administrator privileges"
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes":
+      - "Quick flag for administrator-specific UI branches."
+  -
+    "name": "isManager"
+    "type": "boolean"
+    "readonly": true
+    "description": "Indicates whether the user has manager privileges"
+    "mutation":
+      "mode": "readonly"
+      "notes": "Readonly context field; use it for reading and UI calculations."
+    "related_actions": []
+    "ai_notes":
+      - "Quick flag for manager-specific UI branches."
+"field_groups": []
+"types": []
+"usage":
+  "import": "import { useContext } from '@retailcrm/embed-ui-v1-contexts/remote/user/current'"
+  "call": "const user = useContext()"
+"related_actions": []
+"ai_notes": []

package/docs/custom-contexts/index.json

@@ -0,0 +1,10 @@
+{
+  "package": "@retailcrm/embed-ui-v1-contexts",
+  "resources": [
+    {
+      "id": "order",
+      "uri": "embed-ui-v1-contexts://custom-contexts/order",
+      "file": "docs/custom-contexts/order.yml"
+    }
+  ]
+}

package/docs/custom-contexts/order.yml

@@ -0,0 +1,65 @@
+"custom_context": "order"
+"summary": "Custom fields context for order entity custom fields."
+"language": "en-GB"
+"audience": "ai"
+"public_import":
+  "from": "@retailcrm/embed-ui-v1-contexts/remote/custom"
+  "named":
+    - "useContext"
+    - "useDictionary"
+    - "isTypeOf"
+"supported_kinds":
+  -
+    "kind": "boolean"
+    "type": "boolean|null"
+    "requires_dictionary": false
+  -
+    "kind": "date"
+    "type": "string|null"
+    "requires_dictionary": false
+  -
+    "kind": "datetime"
+    "type": "string|null"
+    "requires_dictionary": false
+  -
+    "kind": "dictionary"
+    "type": "string|null"
+    "requires_dictionary": true
+  -
+    "kind": "multiselect_dictionary"
+    "type": "string[]"
+    "requires_dictionary": true
+  -
+    "kind": "email"
+    "type": "string|null"
+    "requires_dictionary": false
+  -
+    "kind": "integer"
+    "type": "number|null"
+    "requires_dictionary": false
+  -
+    "kind": "numeric"
+    "type": "number|null"
+    "requires_dictionary": false
+  -
+    "kind": "string"
+    "type": "string|null"
+    "requires_dictionary": false
+  -
+    "kind": "text"
+    "type": "string|null"
+    "requires_dictionary": false
+"usage":
+  "initialize": "const custom = useContext('order'); await custom.initialize()"
+  "read": "custom.values[code]"
+  "write": "custom.set(code, value)"
+  "dictionary": "const dictionary = useDictionary(); await dictionary.query(dictionaryCode, { first: 20 })"
+"write_rules":
+  - "Call initialize before reading or writing custom field values."
+  - "Do not write fields marked readonly in the custom schema."
+  - "Use values matching the field kind; invalid values are rejected by the remote store."
+  - "Load dictionaries for dictionary and multiselect_dictionary fields when labels/options are needed."
+"ai_notes":
+  - "Call initialize before reading custom field values."
+  - "Do not write readonly custom fields; the remote store rejects writes according to schema."
+  - "Dictionary and multiselect_dictionary fields require dictionary loading for option labels."

package/docs/ru/CONCEPT.md

@@ -1,13 +1,198 @@
-# Концепт [DRAFT]
+# Предустановленные контексты
 
-Данный пакет предоставляет логику и типы для host и remote окружения. Часть предложенных типов используются одновременно
-в обоих окружениях, в частности `ContextAccessor` и `CustomContextAccessor` – на стороне host'а создаются два таких
-объекта и смешиваются в один, чтобы затем их методы предоставить в качестве удаленного API, который потребляется
-расширениями в remote окружении.
+`@retailcrm/embed-ui-v1-contexts` предоставляет реактивные контексты RetailCRM для JS-расширений.
+Контекст дает расширению доступ к данным страницы CRM, на которой оно запущено: например к форме заказа,
+карточке клиента, текущему пользователю или системным настройкам.
 
-`ContextAccessor` используется для получения/изменения данных некоторого предустановленного контекста, состав которого
-известен заранее. Для доступа к полям указывается название частичного контекста, например, `order/card` и название поля
-в частичном контексте.
+Контексты используются в remote-коде расширения. CRM host передает данные и события через endpoint,
+а расширение работает с ними через публичные composable-утилиты пакета.
 
-`CustomContextAccessor` используется для получения/изменения данных некоторого пользовательского контекста, который
-основан на пользовательских полях. Состав такого контекста заранее неизвестен.
+## Виды контекстов
+
+В пакете есть два вида контекстов:
+
+- Предустановленные контексты — имеют заранее известный набор полей, типы и readonly/writable статус.
+  Примеры: `order/card`, `order/card:settings`, `user/current`, `settings`.
+- Пользовательские контексты — строятся по схеме пользовательских полей CRM, поэтому состав полей заранее
+  неизвестен. Они описаны отдельно в [`CUSTOM.md`](./CUSTOM.md).
+
+Этот документ описывает предустановленные контексты.
+
+## Как выбрать доступный контекст
+
+Доступность контекста зависит от widget target. Для виджетов source of truth находится в
+`@retailcrm/embed-ui-v1-endpoint`: target profile перечисляет `contexts`, `custom_contexts` и `action_scopes`,
+которые доступны в конкретной точке встраивания.
+
+Не нужно выводить доступность контекста из названия страницы или target id. Используйте target config.
+Если target не перечисляет нужный контекст, расширение не должно полагаться на его наличие.
+
+## Использование в remote-коде
+
+Каждый предустановленный контекст экспортирует `useContext` из своего public entrypoint:
+
+```typescript
+import { useContext } from '@retailcrm/embed-ui-v1-contexts/remote/order/card'
+
+const order = useContext()
+```
+
+Контекст работает как Pinia store с реактивными getters/setters для полей схемы. Поля и типы известны из
+соответствующего `types/*.d.ts` и generated profiles.
+
+Пример чтения данных заказа:
+
+```typescript
+import { computed } from 'vue'
+
+import { useContext } from '@retailcrm/embed-ui-v1-contexts/remote/order/card'
+
+const order = useContext()
+
+const hasItems = computed(() => order.items.length > 0)
+const customerEmail = computed(() => order['customer.email'])
+```
+
+Пример записи writable поля:
+
+```typescript
+import { useContext } from '@retailcrm/embed-ui-v1-contexts/remote/order/card'
+
+const order = useContext()
+
+order['discount.percent'] = 10
+order['delivery.address'] = 'Москва, Тверская, 1'
+```
+
+## Readonly и writable поля
+
+Каждое поле схемы имеет флаг `readonly`.
+
+- Readonly поля предназначены для чтения и расчетов UI. Их нельзя менять напрямую.
+- Writable поля можно менять через context store, если изменение соответствует контракту CRM.
+- Если поле является агрегатом или управляется сложной логикой формы, правильный способ изменения может быть action,
+  даже если UI-задача выглядит как изменение одного значения.
+
+Например, в `order/card` поле `items` является readonly source of truth для состава заказа. Для изменения товарных
+позиций используются actions: `changeItemQuantity`, `changeItemPriceType`, `changeItemDiscount`, `removeItem` и другие.
+
+## Actions
+
+Некоторые контексты имеют отдельный action scope. Actions нужны для host-mediated изменений, где прямой set поля
+не отражает бизнес-операцию или невозможен из-за readonly-поля.
+
+Для `order/card` actions экспортируются рядом с context:
+
+```typescript
+import {
+  useActions,
+  useContext,
+} from '@retailcrm/embed-ui-v1-contexts/remote/order/card'
+
+const order = useContext()
+const actions = useActions()
+
+const firstItem = order.items[0]
+
+if (firstItem) {
+  await actions.changeItemQuantity(firstItem.index, firstItem.quantity + 1)
+}
+```
+
+Используйте `OrderItem.index` из текущего `items` как идентификатор позиции при вызове item actions.
+
+## Основные предустановленные контексты
+
+### `order/card`
+
+Данные формы заказа:
+
+- идентификаторы и служебные поля заказа;
+- customer fields;
+- company fields;
+- `items` — readonly список товарных позиций;
+- `delivery.address` — writable адрес доставки;
+- `discount.amount`, `discount.percent` — writable одноразовая скидка заказа;
+- `discount.total` — readonly итоговая скидка;
+- `status` — readonly статус заказа.
+
+Для изменения товарных позиций используйте `useActions()` из
+`@retailcrm/embed-ui-v1-contexts/remote/order/card`.
+
+### `order/card:settings`
+
+Readonly настройки формы заказа. Они нужны, чтобы UI расширения уважал возможности текущей CRM-формы:
+
+- `priceEditable`;
+- `productsRemoveAllowed`;
+- `quantityIsFractional`;
+- `showPriceTypes`;
+- `useStores`;
+- `useReserve`.
+
+Например, если `quantityIsFractional` равен `false`, UI ввода количества не должен предлагать дробные значения.
+
+### `customer/card`
+
+Данные карточки клиента:
+
+- `id`;
+- `externalId`;
+- `type`;
+- `firstName`;
+- `lastName`;
+- `patronymic`.
+
+### `customer/card:phone`
+
+Телефонный контекст карточки клиента. Используется в target, где CRM предоставляет телефон клиента.
+
+### `user/current`
+
+Readonly данные текущего пользователя:
+
+- идентификатор и ФИО;
+- `groups`;
+- `permissions`;
+- `isAdmin`;
+- `isManager`.
+
+Используйте `permissions`, `groups` и quick flags для условного отображения действий в UI расширения.
+
+### `settings`
+
+Readonly системные настройки:
+
+- `system.locale` — локаль CRM;
+- `system.routing` — данные Symfony router для построения CRM route URL;
+- `image.workers` — worker endpoints для обработки изображений.
+
+## Generated AI profiles
+
+При сборке пакета генерируются AI-friendly profiles:
+
+- `docs/contexts/*.yml` — описание предустановленных контекстов;
+- `docs/actions/*.yml` — описание action scopes;
+- `docs/custom-contexts/*.yml` — описание custom context entities;
+- `docs/*/index.json` — индексы generated resources.
+
+Profiles генерируются из typed source metadata и не редактируются вручную:
+
+```bash
+yarn workspace @retailcrm/embed-ui-v1-contexts run build:docs
+```
+
+Полная сборка workspace тоже запускает генерацию:
+
+```bash
+yarn workspace @retailcrm/embed-ui-v1-contexts run build
+```
+
+Release workflow выполняет `yarn workspaces foreach -A --topological-dev run build`, поэтому profiles
+генерируются перед публикацией и входят в published package вместе с `docs`.
+
+## Связанные документы
+
+- [`CUSTOM.md`](./CUSTOM.md) — пользовательские контексты для custom fields.
+- [`@retailcrm/embed-ui-v1-endpoint` targets](../../../v1-endpoint/docs/targets.md) — как определить,
+  какие contexts доступны в widget target.

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@retailcrm/embed-ui-v1-contexts",
+  "bin": {
+    "embed-ui-v1-contexts": "bin/embed-ui-v1-contexts.mjs",
+    "embed-ui-v1-contexts-mcp": "bin/embed-ui-v1-contexts-mcp.mjs"
+  },
   "description": "Reactive contexts for RetailCRM JS API",
   "type": "module",
-  "version": "0.9.23-alpha.2",
+  "version": "0.9.23",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
   "repository": {
@@ -23,6 +27,12 @@
       "require": "./dist/remote.cjs",
       "default": "./dist/remote.js"
     },
+    "./mcp": {
+      "types": "./dist/mcp/server.d.ts",
+      "import": "./dist/mcp/server.js",
+      "require": "./dist/mcp/server.cjs",
+      "default": "./dist/mcp/server.js"
+    },
     "./remote/customer/*": {
       "types": "./dist/remote/customer/*.d.ts",
       "import": "./dist/remote/customer/*.js",
@@ -63,6 +73,9 @@
       "remote": [
         "./dist/remote.d.ts"
       ],
+      "mcp": [
+        "./dist/mcp/server.d.ts"
+      ],
       "remote/customer/card": [
         "./dist/remote/customer/card.d.ts"
       ],
@@ -87,30 +100,34 @@
     }
   },
   "files": [
+    "bin",
     "dist",
     "docs",
     "types",
     "README.md"
   ],
   "scripts": {
-    "build": "yarn prepare && yarn build:code && yarn build:meta",
+    "build": "yarn prepare && yarn build:docs && yarn build:code && yarn build:mcp && yarn build:meta",
     "build:code": "vite build",
+    "build:docs": "npx tsx scripts/build.docs.ts",
+    "build:mcp": "vite build -c ./vite.config.mcp.ts",
     "build:meta": "npx tsx scripts/build.meta.ts",
     "generate:known-types": "npx tsx scripts/generate.known-types.ts",
     "prepare": "yarn generate:known-types",
-    "test": "yarn prepare && vitest --run"
+    "test": "yarn prepare && yarn build:docs && vitest --run"
   },
   "peerDependencies": {
     "@remote-ui/rpc": "^1.4",
     "pinia": "^2.2"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@omnicajs/symfony-router": "^1.0.0",
-    "@retailcrm/embed-ui-v1-types": "^0.9.23-alpha.2"
+    "@retailcrm/embed-ui-v1-types": "^0.9.23"
   },
   "devDependencies": {
     "@remote-ui/rpc": "^1.4.7",
-    "@retailcrm/embed-ui-v1-testing": "^0.9.23-alpha.2",
+    "@retailcrm/embed-ui-v1-testing": "^0.9.23",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vite": "^7.3.2",