@retailcrm/embed-ui 0.9.7 → 0.9.9

package/AGENTS.md

@@ -0,0 +1,128 @@
+# AGENTS.md
+
+## Goals
+- Avoid clarification loops by proposing a concrete interpretation when details are missing.
+- Default to the language of the user's initial message unless they explicitly request a different language.
+- Match the tone and formality of the user's initial message unless they explicitly ask for a change.
+- Treat a language switch in the user's message as an explicit request to respond in that language.
+- If a message is mixed-language, reply in the dominant language unless the user specifies otherwise.
+
+## Purpose
+This file defines practical instructions for working in the `@retailcrm/embed-ui` repository.
+
+## Repository Structure
+- This project is a Yarn Workspaces monorepo.
+- Workspace glob: `packages/*`.
+- Current workspace folders:
+  - `v1-components`
+  - `v1-contexts`
+  - `v1-testing`
+  - `v1-types`
+- Workspace package names may differ from folder names, but commit scopes in this repository are based on workspace folder names.
+
+## Local Environment Prerequisites
+- Yarn version is `4.12.0` (see `packageManager` in `package.json` and `yarnPath` in `.yarnrc.yml`).
+- Package manager mode is `node-modules` (see `.yarnrc.yml`).
+- Local Yarn config is generated from `.yarnrc.dist.yml` using:
+```bash
+make .yarnrc.yml
+```
+- Root install:
+```bash
+yarn install
+```
+
+## Running Checks
+
+### Local Path (without Docker)
+- Prepare Yarn config:
+```bash
+make .yarnrc.yml
+```
+- Install dependencies:
+```bash
+yarn install
+```
+- Build all workspaces:
+```bash
+yarn workspaces foreach -A --topological-dev run build
+```
+- Run lint:
+```bash
+yarn eslint
+```
+- Run tests:
+```bash
+yarn test
+```
+
+### Docker Path (Makefile)
+- Install dependencies in container:
+```bash
+make node_modules
+```
+- Build all workspaces:
+```bash
+make build
+```
+- Run tests:
+```bash
+make tests
+```
+- Pass custom Vitest CLI arguments via Makefile:
+```bash
+make tests cli="-t outOfRangeErrorText"
+```
+
+## Related Commands
+- Build root package only:
+```bash
+yarn build
+```
+- Build root code artifacts only:
+```bash
+yarn build:code
+```
+- Build root meta artifacts only:
+```bash
+yarn build:meta
+```
+- Build Storybook for `v1-components`:
+```bash
+yarn workspace @retailcrm/embed-ui-v1-components run storybook:build
+```
+
+## Commit Workflow
+- Commit format: Conventional Commits.
+- Commit message language: English.
+- Scope rule: use workspace folder name (not npm package name).
+- Valid workspace scopes currently are:
+  - `v1-components`
+  - `v1-contexts`
+  - `v1-testing`
+  - `v1-types`
+- For root/global changes, scope may be omitted.
+- Split commits by logical intent.
+- Keep commit subject concise and factual.
+- Start commit subject description with an uppercase letter.
+- Mention affected component(s) or area in subject description when applicable.
+- Commit subject should describe completed change in past tense.
+- Prefer passive voice for changelog-friendly phrasing.
+- Do not amend/rewrite history unless explicitly requested.
+
+Examples:
+- `feat(v1-components): UiSelect searchable option group header added`
+- `fix(v1-contexts): OrderContext missing customer id handling corrected`
+- `docs: AGENTS commit workflow section updated`
+
+## Skills
+- Repository-local skills are available under `skills/`.
+- If a skill conflicts with this file, follow `AGENTS.md`.
+- Current local skills:
+  - `skills/commit-workflow/SKILL.md`
+  - `skills/sync-remote-host-registry/SKILL.md`
+  - `skills/yarn-lock-conflict-resolution/SKILL.md`
+
+## Notes
+- Do not assume legacy rules from other repositories (especially `omnica`) apply here.
+- If repository policy is unclear, ask a short clarifying question before making irreversible actions.

package/ARCHITECTURE.md

@@ -0,0 +1,143 @@
+# Архитектура `@retailcrm/embed-ui`
+
+## 1. Назначение
+
+Репозиторий содержит библиотечный слой для JS-расширений RetailCRM:
+
+- контракт и транспорт между `remote` (код расширения) и `host` (CRM-страница);
+- UI-компоненты с разделением на remote-описания и host-реализации;
+- реактивные контексты (предопределенные и пользовательские);
+- вспомогательные типы и тестовые утилиты.
+
+Ключевая идея: расширение не рендерит «реальный DOM» CRM напрямую.  
+Оно отправляет инструкции рендера и вызовов в host-часть через RPC/remote-runtime.
+
+## 2. Структура монорепозитория
+
+Монорепозиторий на Yarn Workspaces (`packages/*`), Yarn `4.12.0`, linker `node-modules`.
+
+### `src/` (корневой пакет `@retailcrm/embed-ui`)
+
+- точка входа SDK для расширений;
+- `createWidgetEndpoint(widget, messenger)` поднимает endpoint и lifecycle `run/release`;
+- создает remote-root с whitelist host-компонентов (`createRoot`);
+- подключает Pinia + плагины доступа к контекстам (`injectEndpoint`, `injectAccessor`);
+- экспортирует публичный API контекстов и composables (`useField`, `useCustomField`, `useHost`, `useRouter`).
+
+### `packages/v1-components`
+
+- UI-библиотека разделена на два entrypoint:
+- `src/host.ts`: host-компоненты для реального рендера в CRM;
+- `src/remote.ts`: remote-компоненты (описания/схемы для передачи в host).
+- Storybook живет здесь и используется как витрина компонентов и сценариев.
+
+### `packages/v1-contexts`
+
+- слой реактивных контекстов и action-вызовов;
+- `src/host.ts`: сборка host-accessor’ов (`createGetter`, `createSetter`, `createContextAccessor`, `createCustomContextAccessor`) и типизированные ошибки (`HostError`, `LogicalError`, `RuntimeError`);
+- `src/remote.ts`: Pinia-обертки для предопределенных контекстов (`defineContext`) и инвокаций (`defineActions`);
+- `src/remote/custom.ts`: доступ к пользовательским полям и словарям.
+
+### `packages/v1-types`
+
+- базовые TS-контракты (контексты, поля, отклонения, action-схемы и пр.);
+- используется всеми остальными workspace.
+
+### `packages/v1-testing`
+
+- тестовые утилиты для runtime-сценариев (RPC/polyfill и хелперы событий).
+
+## 3. Runtime-модель host/remote
+
+### 3.1 Поток инициализации виджета
+
+1. CRM (host) создает `messenger` и вызывает `createWidgetEndpoint(...)` из корневого SDK.
+2. SDK поднимает RPC endpoint и экспортирует методы lifecycle: `run(channel, target)`, `release()`.
+3. При `run(...)` создается remote-root с допустимыми host-компонентами, инициализируется Pinia с endpoint-плагинами контекстов, после чего вызывается `widget.run(createApp, root, pinia, target)`.
+4. При `release()` вызывается destroy-функция виджета и освобождаются RPC-ресурсы.
+
+### 3.2 Каналы ответственности
+
+- `remote`: бизнес-логика расширения, декларативная сборка UI через remote-компоненты, чтение/запись контекстов через Pinia stores.
+- `host`: фактический рендер, геометрия, DOM, popper/positioning, интерактивность, предоставление данных контекста и invokable-методов (`goTo`, `httpCall`, domain actions).
+
+## 4. Архитектура компонентов
+
+### 4.1 Общий паттерн
+
+Для большинства компонентов сохраняется 1:1 соответствие:
+
+- remote-компонент описывает схему и события;
+- host-компонент выполняет фактический рендер.
+
+Примеры: `UiButton`, `UiCheckbox`, `UiTooltip`.
+
+### 4.2 Важный частный случай: `UiSelect`
+
+`UiSelect` — первый явно композиционный пример, где соответствие не 1:1:
+
+- remote-слой содержит семейство: `UiSelect`, `UiSelectOption`, `UiSelectOptionGroup`, `UiSelectOptionGroupHeader`;
+- host-рендер опирается на `UiSelectTrigger` + `UiSelectPopper` + menu/popper-примитивы;
+- состояние выбора/фильтрации и регистрация опций координируются через `provide/inject`-ключи.
+
+Следствие: host-реестр компонентов должен отражать не только «публичные remote-компоненты», но и необходимые host-примитивы, из которых они фактически собираются.
+
+### 4.3 Реестр host-компонентов: что в него входит
+
+Реестр в `src/index.ts` должен содержать только те host-компоненты, которые достижимы из remote-схемы рендера.
+
+- часть host-компонентов может быть внутренней (не remote-публичной) и потому не обязана попадать в реестр root SDK;
+- обратный случай тоже возможен: один remote-компонент может требовать несколько host-примитивов;
+- пример host-only компонента: `UiToolbar` экспортируется в `v1-components/host`, но не участвует в текущем remote render graph корневого SDK.
+
+## 5. Контексты и данные
+
+### 5.1 Предопределенные контексты
+
+- контекст задается описанием схемы полей;
+- remote-store инициализируется через `endpoint.call.get(context, '~')`;
+- подписки на изменения поля устанавливаются через `endpoint.call.on('change:field', ...)`;
+- запись идет через `endpoint.call.set(...)` с валидацией по schema.
+
+### 5.2 Пользовательские контексты (custom fields)
+
+- схема контекста запрашивается динамически у host;
+- значения и типы полей становятся известны после `initialize()`;
+- чтение/запись выполняются через `getCustomField/setCustomField`;
+- словари грузятся отдельным каналом `getCustomDictionary`.
+
+### 5.3 Ошибки и отклонения
+
+- host-часть разделяет логические и runtime-ошибки;
+- remote-часть может получать `Rejection` через callback `onReject`;
+- в composables заданы безопасные обработчики по умолчанию (логирование в `console.error`).
+
+## 6. Storybook как архитектурная песочница
+
+`packages/v1-components/storybook` выполняет две роли:
+
+- документация и интерактивная проверка host-компонентов;
+- демонстрация host/remote-связки (сейчас явно показана в `UiSelect`-истории через worker + endpoint + HostedTree/provider/receiver).
+
+Текущее состояние: bridge-механика визуально раскрыта не во всех историях, что усложняет onboarding для новых участников.
+
+## 7. Сборка, релиз, CI
+
+- сборка корня: `vite build` + генерация meta (`scripts/build.meta.ts`);
+- workspace-сборка в CI: `yarn workspaces foreach -A --topological-dev run build`;
+- тестовый workflow: Node `22.x` и `24.x`, шаги build + eslint + test;
+- release workflow: build/lint/test, bump/release scripts, публикация npm, деплой Storybook (`version` + обновление `latest`).
+
+## 8. Дальнейшее развитие качества
+
+Следующий этап развития проекта направлен на усиление автоматизированного контроля качества и формализацию ключевых архитектурных инвариантов.
+
+## 9. Планы по усилению контроля качества
+
+Ближайшие шаги:
+
+1. Ввести обязательный typecheck в локальный и CI-пайплайн.
+2. Расширить тесты на ключевые контракты host/remote и на синхронизацию реестров компонентов.
+3. Добавить автоматические проверки целостности render graph (минимум smoke/contract test).
+4. Расширить Storybook-документацию: явно показывать host/remote-binding не только для `UiSelect`.
+5. После стабилизации перейти к автоматизации registry/provider (кодогенерация) как к следующему этапу эволюции.

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
 
+## [0.9.9](https://github.com/retailcrm/embed-ui/compare/v0.9.8...v0.9.9) (2026-02-12)
+
+### Bug Fixes
+
+* **v1-components:** apply vue plugins to storybook worker build ([5054dd7](https://github.com/retailcrm/embed-ui/commit/5054dd700948770b1eecabd37f9ec67a32ab4e55))
+## [0.9.8](https://github.com/retailcrm/embed-ui/compare/v0.9.7...v0.9.8) (2026-02-12)
+
+### Features
+
+* **v1-components:** UiSelect, UiMenuItem components added ([7980397](https://github.com/retailcrm/embed-ui/commit/7980397c83c20bf92453b5c9b2ba3eda4f6da93f))
+
+### Bug Fixes
+
+* CreateRoot host registry was synchronized with v1-components render graph ([eaa04a8](https://github.com/retailcrm/embed-ui/commit/eaa04a88712116ffeb7c4af047d419abff4e8847))
 ## [0.9.7](https://github.com/retailcrm/embed-ui/compare/v0.9.6...v0.9.7) (2026-01-13)
 
 ### Bug Fixes

package/Makefile

@@ -39,6 +39,30 @@ else
 	$(YARN) test
 endif
 
+.PHONY: tests-coverage
+tests-coverage: ## Runs autotests with coverage report
+	$(TARGET_HEADER)
+ifdef cli
+	$(YARN) vitest --run --coverage $(cli) --passWithNoTests
+else
+	$(YARN) test:coverage
+endif
+
+.PHONY: tests-typecheck-contexts
+tests-typecheck-contexts: ## Runs typecheck tests (test-d.ts) for v1-contexts
+	$(TARGET_HEADER)
+ifdef cli
+	$(YARN) vitest run -c packages/v1-contexts/vitest.config.ts --typecheck.only --typecheck.checker tsc --typecheck.tsconfig packages/v1-contexts/tsconfig.json $(cli)
+else
+	$(YARN) vitest run -c packages/v1-contexts/vitest.config.ts --typecheck.only --typecheck.checker tsc --typecheck.tsconfig packages/v1-contexts/tsconfig.json
+endif
+
+.PHONY: tests-typecheck-v1-contexts
+tests-typecheck-v1-contexts: tests-typecheck-contexts ## Alias for tests-typecheck-contexts
+
+.PHONY: tests-typecheck
+tests-typecheck: tests-typecheck-contexts ## Runs typecheck tests (currently v1-contexts)
+
 .PHONY: help
 help: ## Calls recipes list
 	@cat $(MAKEFILE_LIST) | grep -e "^[a-zA-Z_\-]*: *.*## *" | awk '\

package/coverage/base.css

@@ -0,0 +1,224 @@
+body, html {
+  margin:0; padding: 0;
+  height: 100%;
+}
+body {
+    font-family: Helvetica Neue, Helvetica, Arial;
+    font-size: 14px;
+    color:#333;
+}
+.small { font-size: 12px; }
+*, *:after, *:before {
+  -webkit-box-sizing:border-box;
+     -moz-box-sizing:border-box;
+          box-sizing:border-box;
+  }
+h1 { font-size: 20px; margin: 0;}
+h2 { font-size: 14px; }
+pre {
+    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
+    margin: 0;
+    padding: 0;
+    -moz-tab-size: 2;
+    -o-tab-size:  2;
+    tab-size: 2;
+}
+a { color:#0074D9; text-decoration:none; }
+a:hover { text-decoration:underline; }
+.strong { font-weight: bold; }
+.space-top1 { padding: 10px 0 0 0; }
+.pad2y { padding: 20px 0; }
+.pad1y { padding: 10px 0; }
+.pad2x { padding: 0 20px; }
+.pad2 { padding: 20px; }
+.pad1 { padding: 10px; }
+.space-left2 { padding-left:55px; }
+.space-right2 { padding-right:20px; }
+.center { text-align:center; }
+.clearfix { display:block; }
+.clearfix:after {
+  content:'';
+  display:block;
+  height:0;
+  clear:both;
+  visibility:hidden;
+  }
+.fl { float: left; }
+@media only screen and (max-width:640px) {
+  .col3 { width:100%; max-width:100%; }
+  .hide-mobile { display:none!important; }
+}
+
+.quiet {
+  color: #7f7f7f;
+  color: rgba(0,0,0,0.5);
+}
+.quiet a { opacity: 0.7; }
+
+.fraction {
+  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+  font-size: 10px;
+  color: #555;
+  background: #E8E8E8;
+  padding: 4px 5px;
+  border-radius: 3px;
+  vertical-align: middle;
+}
+
+div.path a:link, div.path a:visited { color: #333; }
+table.coverage {
+  border-collapse: collapse;
+  margin: 10px 0 0 0;
+  padding: 0;
+}
+
+table.coverage td {
+  margin: 0;
+  padding: 0;
+  vertical-align: top;
+}
+table.coverage td.line-count {
+    text-align: right;
+    padding: 0 5px 0 20px;
+}
+table.coverage td.line-coverage {
+    text-align: right;
+    padding-right: 10px;
+    min-width:20px;
+}
+
+table.coverage td span.cline-any {
+    display: inline-block;
+    padding: 0 5px;
+    width: 100%;
+}
+.missing-if-branch {
+    display: inline-block;
+    margin-right: 5px;
+    border-radius: 3px;
+    position: relative;
+    padding: 0 4px;
+    background: #333;
+    color: yellow;
+}
+
+.skip-if-branch {
+    display: none;
+    margin-right: 10px;
+    position: relative;
+    padding: 0 4px;
+    background: #ccc;
+    color: white;
+}
+.missing-if-branch .typ, .skip-if-branch .typ {
+    color: inherit !important;
+}
+.coverage-summary {
+  border-collapse: collapse;
+  width: 100%;
+}
+.coverage-summary tr { border-bottom: 1px solid #bbb; }
+.keyline-all { border: 1px solid #ddd; }
+.coverage-summary td, .coverage-summary th { padding: 10px; }
+.coverage-summary tbody { border: 1px solid #bbb; }
+.coverage-summary td { border-right: 1px solid #bbb; }
+.coverage-summary td:last-child { border-right: none; }
+.coverage-summary th {
+  text-align: left;
+  font-weight: normal;
+  white-space: nowrap;
+}
+.coverage-summary th.file { border-right: none !important; }
+.coverage-summary th.pct { }
+.coverage-summary th.pic,
+.coverage-summary th.abs,
+.coverage-summary td.pct,
+.coverage-summary td.abs { text-align: right; }
+.coverage-summary td.file { white-space: nowrap;  }
+.coverage-summary td.pic { min-width: 120px !important;  }
+.coverage-summary tfoot td { }
+
+.coverage-summary .sorter {
+    height: 10px;
+    width: 7px;
+    display: inline-block;
+    margin-left: 0.5em;
+    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
+}
+.coverage-summary .sorted .sorter {
+    background-position: 0 -20px;
+}
+.coverage-summary .sorted-desc .sorter {
+    background-position: 0 -10px;
+}
+.status-line {  height: 10px; }
+/* yellow */
+.cbranch-no { background: yellow !important; color: #111; }
+/* dark red */
+.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
+.low .chart { border:1px solid #C21F39 }
+.highlighted,
+.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
+  background: #C21F39 !important;
+}
+/* medium red */
+.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
+/* light red */
+.low, .cline-no { background:#FCE1E5 }
+/* light green */
+.high, .cline-yes { background:rgb(230,245,208) }
+/* medium green */
+.cstat-yes { background:rgb(161,215,106) }
+/* dark green */
+.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
+.high .chart { border:1px solid rgb(77,146,33) }
+/* dark yellow (gold) */
+.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
+.medium .chart { border:1px solid #f9cd0b; }
+/* light yellow */
+.medium { background: #fff4c2; }
+
+.cstat-skip { background: #ddd; color: #111; }
+.fstat-skip { background: #ddd; color: #111 !important; }
+.cbranch-skip { background: #ddd !important; color: #111; }
+
+span.cline-neutral { background: #eaeaea; }
+
+.coverage-summary td.empty {
+    opacity: .5;
+    padding-top: 4px;
+    padding-bottom: 4px;
+    line-height: 1;
+    color: #888;
+}
+
+.cover-fill, .cover-empty {
+  display:inline-block;
+  height: 12px;
+}
+.chart {
+  line-height: 0;
+}
+.cover-empty {
+    background: white;
+}
+.cover-full {
+    border-right: none !important;
+}
+pre.prettyprint {
+    border: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+}
+.com { color: #999 !important; }
+.ignore-none { color: #999; font-weight: normal; }
+
+.wrapper {
+  min-height: 100%;
+  height: auto !important;
+  height: 100%;
+  margin: 0 auto -48px;
+}
+.footer, .push {
+  height: 48px;
+}

package/coverage/block-navigation.js

@@ -0,0 +1,87 @@
+/* eslint-disable */
+var jumpToCode = (function init() {
+    // Classes of code we would like to highlight in the file view
+    var missingCoverageClasses = ['.cbranch-no', '.cstat-no', '.fstat-no'];
+
+    // Elements to highlight in the file listing view
+    var fileListingElements = ['td.pct.low'];
+
+    // We don't want to select elements that are direct descendants of another match
+    var notSelector = ':not(' + missingCoverageClasses.join('):not(') + ') > '; // becomes `:not(a):not(b) > `
+
+    // Selector that finds elements on the page to which we can jump
+    var selector =
+        fileListingElements.join(', ') +
+        ', ' +
+        notSelector +
+        missingCoverageClasses.join(', ' + notSelector); // becomes `:not(a):not(b) > a, :not(a):not(b) > b`
+
+    // The NodeList of matching elements
+    var missingCoverageElements = document.querySelectorAll(selector);
+
+    var currentIndex;
+
+    function toggleClass(index) {
+        missingCoverageElements
+            .item(currentIndex)
+            .classList.remove('highlighted');
+        missingCoverageElements.item(index).classList.add('highlighted');
+    }
+
+    function makeCurrent(index) {
+        toggleClass(index);
+        currentIndex = index;
+        missingCoverageElements.item(index).scrollIntoView({
+            behavior: 'smooth',
+            block: 'center',
+            inline: 'center'
+        });
+    }
+
+    function goToPrevious() {
+        var nextIndex = 0;
+        if (typeof currentIndex !== 'number' || currentIndex === 0) {
+            nextIndex = missingCoverageElements.length - 1;
+        } else if (missingCoverageElements.length > 1) {
+            nextIndex = currentIndex - 1;
+        }
+
+        makeCurrent(nextIndex);
+    }
+
+    function goToNext() {
+        var nextIndex = 0;
+
+        if (
+            typeof currentIndex === 'number' &&
+            currentIndex < missingCoverageElements.length - 1
+        ) {
+            nextIndex = currentIndex + 1;
+        }
+
+        makeCurrent(nextIndex);
+    }
+
+    return function jump(event) {
+        if (
+            document.getElementById('fileSearch') === document.activeElement &&
+            document.activeElement != null
+        ) {
+            // if we're currently focused on the search input, we don't want to navigate
+            return;
+        }
+
+        switch (event.which) {
+            case 78: // n
+            case 74: // j
+                goToNext();
+                break;
+            case 66: // b
+            case 75: // k
+            case 80: // p
+                goToPrevious();
+                break;
+        }
+    };
+})();
+window.addEventListener('keydown', jumpToCode);