@retailcrm/embed-ui 0.9.7 → 0.9.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +128 -0
- package/ARCHITECTURE.md +143 -0
- package/CHANGELOG.md +9 -0
- package/Makefile +15 -0
- package/dist/index.cjs +4 -0
- package/dist/index.mjs +4 -0
- package/dist/meta.json +1 -1
- package/index.d.ts +1 -1
- package/package.json +4 -4
- package/skills/commit-workflow/SKILL.md +77 -0
- package/skills/sync-remote-host-registry/SKILL.md +62 -0
- package/skills/yarn-lock-conflict-resolution/SKILL.md +76 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
## Goals
|
|
4
|
+
- Avoid clarification loops by proposing a concrete interpretation when details are missing.
|
|
5
|
+
- Default to the language of the user's initial message unless they explicitly request a different language.
|
|
6
|
+
- Match the tone and formality of the user's initial message unless they explicitly ask for a change.
|
|
7
|
+
- Treat a language switch in the user's message as an explicit request to respond in that language.
|
|
8
|
+
- If a message is mixed-language, reply in the dominant language unless the user specifies otherwise.
|
|
9
|
+
|
|
10
|
+
## Purpose
|
|
11
|
+
This file defines practical instructions for working in the `@retailcrm/embed-ui` repository.
|
|
12
|
+
|
|
13
|
+
## Repository Structure
|
|
14
|
+
- This project is a Yarn Workspaces monorepo.
|
|
15
|
+
- Workspace glob: `packages/*`.
|
|
16
|
+
- Current workspace folders:
|
|
17
|
+
- `v1-components`
|
|
18
|
+
- `v1-contexts`
|
|
19
|
+
- `v1-testing`
|
|
20
|
+
- `v1-types`
|
|
21
|
+
- Workspace package names may differ from folder names, but commit scopes in this repository are based on workspace folder names.
|
|
22
|
+
|
|
23
|
+
## Local Environment Prerequisites
|
|
24
|
+
- Yarn version is `4.12.0` (see `packageManager` in `package.json` and `yarnPath` in `.yarnrc.yml`).
|
|
25
|
+
- Package manager mode is `node-modules` (see `.yarnrc.yml`).
|
|
26
|
+
- Local Yarn config is generated from `.yarnrc.dist.yml` using:
|
|
27
|
+
```bash
|
|
28
|
+
make .yarnrc.yml
|
|
29
|
+
```
|
|
30
|
+
- Root install:
|
|
31
|
+
```bash
|
|
32
|
+
yarn install
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Running Checks
|
|
36
|
+
|
|
37
|
+
### Local Path (without Docker)
|
|
38
|
+
- Prepare Yarn config:
|
|
39
|
+
```bash
|
|
40
|
+
make .yarnrc.yml
|
|
41
|
+
```
|
|
42
|
+
- Install dependencies:
|
|
43
|
+
```bash
|
|
44
|
+
yarn install
|
|
45
|
+
```
|
|
46
|
+
- Build all workspaces:
|
|
47
|
+
```bash
|
|
48
|
+
yarn workspaces foreach -A --topological-dev run build
|
|
49
|
+
```
|
|
50
|
+
- Run lint:
|
|
51
|
+
```bash
|
|
52
|
+
yarn eslint
|
|
53
|
+
```
|
|
54
|
+
- Run tests:
|
|
55
|
+
```bash
|
|
56
|
+
yarn test
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Docker Path (Makefile)
|
|
60
|
+
- Install dependencies in container:
|
|
61
|
+
```bash
|
|
62
|
+
make node_modules
|
|
63
|
+
```
|
|
64
|
+
- Build all workspaces:
|
|
65
|
+
```bash
|
|
66
|
+
make build
|
|
67
|
+
```
|
|
68
|
+
- Run tests:
|
|
69
|
+
```bash
|
|
70
|
+
make tests
|
|
71
|
+
```
|
|
72
|
+
- Pass custom Vitest CLI arguments via Makefile:
|
|
73
|
+
```bash
|
|
74
|
+
make tests cli="-t outOfRangeErrorText"
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Related Commands
|
|
78
|
+
- Build root package only:
|
|
79
|
+
```bash
|
|
80
|
+
yarn build
|
|
81
|
+
```
|
|
82
|
+
- Build root code artifacts only:
|
|
83
|
+
```bash
|
|
84
|
+
yarn build:code
|
|
85
|
+
```
|
|
86
|
+
- Build root meta artifacts only:
|
|
87
|
+
```bash
|
|
88
|
+
yarn build:meta
|
|
89
|
+
```
|
|
90
|
+
- Build Storybook for `v1-components`:
|
|
91
|
+
```bash
|
|
92
|
+
yarn workspace @retailcrm/embed-ui-v1-components run storybook:build
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Commit Workflow
|
|
96
|
+
- Commit format: Conventional Commits.
|
|
97
|
+
- Commit message language: English.
|
|
98
|
+
- Scope rule: use workspace folder name (not npm package name).
|
|
99
|
+
- Valid workspace scopes currently are:
|
|
100
|
+
- `v1-components`
|
|
101
|
+
- `v1-contexts`
|
|
102
|
+
- `v1-testing`
|
|
103
|
+
- `v1-types`
|
|
104
|
+
- For root/global changes, scope may be omitted.
|
|
105
|
+
- Split commits by logical intent.
|
|
106
|
+
- Keep commit subject concise and factual.
|
|
107
|
+
- Start commit subject description with an uppercase letter.
|
|
108
|
+
- Mention affected component(s) or area in subject description when applicable.
|
|
109
|
+
- Commit subject should describe completed change in past tense.
|
|
110
|
+
- Prefer passive voice for changelog-friendly phrasing.
|
|
111
|
+
- Do not amend/rewrite history unless explicitly requested.
|
|
112
|
+
|
|
113
|
+
Examples:
|
|
114
|
+
- `feat(v1-components): UiSelect searchable option group header added`
|
|
115
|
+
- `fix(v1-contexts): OrderContext missing customer id handling corrected`
|
|
116
|
+
- `docs: AGENTS commit workflow section updated`
|
|
117
|
+
|
|
118
|
+
## Skills
|
|
119
|
+
- Repository-local skills are available under `skills/`.
|
|
120
|
+
- If a skill conflicts with this file, follow `AGENTS.md`.
|
|
121
|
+
- Current local skills:
|
|
122
|
+
- `skills/commit-workflow/SKILL.md`
|
|
123
|
+
- `skills/sync-remote-host-registry/SKILL.md`
|
|
124
|
+
- `skills/yarn-lock-conflict-resolution/SKILL.md`
|
|
125
|
+
|
|
126
|
+
## Notes
|
|
127
|
+
- Do not assume legacy rules from other repositories (especially `omnica`) apply here.
|
|
128
|
+
- If repository policy is unclear, ask a short clarifying question before making irreversible actions.
|
package/ARCHITECTURE.md
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# Архитектура `@retailcrm/embed-ui`
|
|
2
|
+
|
|
3
|
+
## 1. Назначение
|
|
4
|
+
|
|
5
|
+
Репозиторий содержит библиотечный слой для JS-расширений RetailCRM:
|
|
6
|
+
|
|
7
|
+
- контракт и транспорт между `remote` (код расширения) и `host` (CRM-страница);
|
|
8
|
+
- UI-компоненты с разделением на remote-описания и host-реализации;
|
|
9
|
+
- реактивные контексты (предопределенные и пользовательские);
|
|
10
|
+
- вспомогательные типы и тестовые утилиты.
|
|
11
|
+
|
|
12
|
+
Ключевая идея: расширение не рендерит «реальный DOM» CRM напрямую.
|
|
13
|
+
Оно отправляет инструкции рендера и вызовов в host-часть через RPC/remote-runtime.
|
|
14
|
+
|
|
15
|
+
## 2. Структура монорепозитория
|
|
16
|
+
|
|
17
|
+
Монорепозиторий на Yarn Workspaces (`packages/*`), Yarn `4.12.0`, linker `node-modules`.
|
|
18
|
+
|
|
19
|
+
### `src/` (корневой пакет `@retailcrm/embed-ui`)
|
|
20
|
+
|
|
21
|
+
- точка входа SDK для расширений;
|
|
22
|
+
- `createWidgetEndpoint(widget, messenger)` поднимает endpoint и lifecycle `run/release`;
|
|
23
|
+
- создает remote-root с whitelist host-компонентов (`createRoot`);
|
|
24
|
+
- подключает Pinia + плагины доступа к контекстам (`injectEndpoint`, `injectAccessor`);
|
|
25
|
+
- экспортирует публичный API контекстов и composables (`useField`, `useCustomField`, `useHost`, `useRouter`).
|
|
26
|
+
|
|
27
|
+
### `packages/v1-components`
|
|
28
|
+
|
|
29
|
+
- UI-библиотека разделена на два entrypoint:
|
|
30
|
+
- `src/host.ts`: host-компоненты для реального рендера в CRM;
|
|
31
|
+
- `src/remote.ts`: remote-компоненты (описания/схемы для передачи в host).
|
|
32
|
+
- Storybook живет здесь и используется как витрина компонентов и сценариев.
|
|
33
|
+
|
|
34
|
+
### `packages/v1-contexts`
|
|
35
|
+
|
|
36
|
+
- слой реактивных контекстов и action-вызовов;
|
|
37
|
+
- `src/host.ts`: сборка host-accessor’ов (`createGetter`, `createSetter`, `createContextAccessor`, `createCustomContextAccessor`) и типизированные ошибки (`HostError`, `LogicalError`, `RuntimeError`);
|
|
38
|
+
- `src/remote.ts`: Pinia-обертки для предопределенных контекстов (`defineContext`) и инвокаций (`defineActions`);
|
|
39
|
+
- `src/remote/custom.ts`: доступ к пользовательским полям и словарям.
|
|
40
|
+
|
|
41
|
+
### `packages/v1-types`
|
|
42
|
+
|
|
43
|
+
- базовые TS-контракты (контексты, поля, отклонения, action-схемы и пр.);
|
|
44
|
+
- используется всеми остальными workspace.
|
|
45
|
+
|
|
46
|
+
### `packages/v1-testing`
|
|
47
|
+
|
|
48
|
+
- тестовые утилиты для runtime-сценариев (RPC/polyfill и хелперы событий).
|
|
49
|
+
|
|
50
|
+
## 3. Runtime-модель host/remote
|
|
51
|
+
|
|
52
|
+
### 3.1 Поток инициализации виджета
|
|
53
|
+
|
|
54
|
+
1. CRM (host) создает `messenger` и вызывает `createWidgetEndpoint(...)` из корневого SDK.
|
|
55
|
+
2. SDK поднимает RPC endpoint и экспортирует методы lifecycle: `run(channel, target)`, `release()`.
|
|
56
|
+
3. При `run(...)` создается remote-root с допустимыми host-компонентами, инициализируется Pinia с endpoint-плагинами контекстов, после чего вызывается `widget.run(createApp, root, pinia, target)`.
|
|
57
|
+
4. При `release()` вызывается destroy-функция виджета и освобождаются RPC-ресурсы.
|
|
58
|
+
|
|
59
|
+
### 3.2 Каналы ответственности
|
|
60
|
+
|
|
61
|
+
- `remote`: бизнес-логика расширения, декларативная сборка UI через remote-компоненты, чтение/запись контекстов через Pinia stores.
|
|
62
|
+
- `host`: фактический рендер, геометрия, DOM, popper/positioning, интерактивность, предоставление данных контекста и invokable-методов (`goTo`, `httpCall`, domain actions).
|
|
63
|
+
|
|
64
|
+
## 4. Архитектура компонентов
|
|
65
|
+
|
|
66
|
+
### 4.1 Общий паттерн
|
|
67
|
+
|
|
68
|
+
Для большинства компонентов сохраняется 1:1 соответствие:
|
|
69
|
+
|
|
70
|
+
- remote-компонент описывает схему и события;
|
|
71
|
+
- host-компонент выполняет фактический рендер.
|
|
72
|
+
|
|
73
|
+
Примеры: `UiButton`, `UiCheckbox`, `UiTooltip`.
|
|
74
|
+
|
|
75
|
+
### 4.2 Важный частный случай: `UiSelect`
|
|
76
|
+
|
|
77
|
+
`UiSelect` — первый явно композиционный пример, где соответствие не 1:1:
|
|
78
|
+
|
|
79
|
+
- remote-слой содержит семейство: `UiSelect`, `UiSelectOption`, `UiSelectOptionGroup`, `UiSelectOptionGroupHeader`;
|
|
80
|
+
- host-рендер опирается на `UiSelectTrigger` + `UiSelectPopper` + menu/popper-примитивы;
|
|
81
|
+
- состояние выбора/фильтрации и регистрация опций координируются через `provide/inject`-ключи.
|
|
82
|
+
|
|
83
|
+
Следствие: host-реестр компонентов должен отражать не только «публичные remote-компоненты», но и необходимые host-примитивы, из которых они фактически собираются.
|
|
84
|
+
|
|
85
|
+
### 4.3 Реестр host-компонентов: что в него входит
|
|
86
|
+
|
|
87
|
+
Реестр в `src/index.ts` должен содержать только те host-компоненты, которые достижимы из remote-схемы рендера.
|
|
88
|
+
|
|
89
|
+
- часть host-компонентов может быть внутренней (не remote-публичной) и потому не обязана попадать в реестр root SDK;
|
|
90
|
+
- обратный случай тоже возможен: один remote-компонент может требовать несколько host-примитивов;
|
|
91
|
+
- пример host-only компонента: `UiToolbar` экспортируется в `v1-components/host`, но не участвует в текущем remote render graph корневого SDK.
|
|
92
|
+
|
|
93
|
+
## 5. Контексты и данные
|
|
94
|
+
|
|
95
|
+
### 5.1 Предопределенные контексты
|
|
96
|
+
|
|
97
|
+
- контекст задается описанием схемы полей;
|
|
98
|
+
- remote-store инициализируется через `endpoint.call.get(context, '~')`;
|
|
99
|
+
- подписки на изменения поля устанавливаются через `endpoint.call.on('change:field', ...)`;
|
|
100
|
+
- запись идет через `endpoint.call.set(...)` с валидацией по schema.
|
|
101
|
+
|
|
102
|
+
### 5.2 Пользовательские контексты (custom fields)
|
|
103
|
+
|
|
104
|
+
- схема контекста запрашивается динамически у host;
|
|
105
|
+
- значения и типы полей становятся известны после `initialize()`;
|
|
106
|
+
- чтение/запись выполняются через `getCustomField/setCustomField`;
|
|
107
|
+
- словари грузятся отдельным каналом `getCustomDictionary`.
|
|
108
|
+
|
|
109
|
+
### 5.3 Ошибки и отклонения
|
|
110
|
+
|
|
111
|
+
- host-часть разделяет логические и runtime-ошибки;
|
|
112
|
+
- remote-часть может получать `Rejection` через callback `onReject`;
|
|
113
|
+
- в composables заданы безопасные обработчики по умолчанию (логирование в `console.error`).
|
|
114
|
+
|
|
115
|
+
## 6. Storybook как архитектурная песочница
|
|
116
|
+
|
|
117
|
+
`packages/v1-components/storybook` выполняет две роли:
|
|
118
|
+
|
|
119
|
+
- документация и интерактивная проверка host-компонентов;
|
|
120
|
+
- демонстрация host/remote-связки (сейчас явно показана в `UiSelect`-истории через worker + endpoint + HostedTree/provider/receiver).
|
|
121
|
+
|
|
122
|
+
Текущее состояние: bridge-механика визуально раскрыта не во всех историях, что усложняет onboarding для новых участников.
|
|
123
|
+
|
|
124
|
+
## 7. Сборка, релиз, CI
|
|
125
|
+
|
|
126
|
+
- сборка корня: `vite build` + генерация meta (`scripts/build.meta.ts`);
|
|
127
|
+
- workspace-сборка в CI: `yarn workspaces foreach -A --topological-dev run build`;
|
|
128
|
+
- тестовый workflow: Node `22.x` и `24.x`, шаги build + eslint + test;
|
|
129
|
+
- release workflow: build/lint/test, bump/release scripts, публикация npm, деплой Storybook (`version` + обновление `latest`).
|
|
130
|
+
|
|
131
|
+
## 8. Дальнейшее развитие качества
|
|
132
|
+
|
|
133
|
+
Следующий этап развития проекта направлен на усиление автоматизированного контроля качества и формализацию ключевых архитектурных инвариантов.
|
|
134
|
+
|
|
135
|
+
## 9. Планы по усилению контроля качества
|
|
136
|
+
|
|
137
|
+
Ближайшие шаги:
|
|
138
|
+
|
|
139
|
+
1. Ввести обязательный typecheck в локальный и CI-пайплайн.
|
|
140
|
+
2. Расширить тесты на ключевые контракты host/remote и на синхронизацию реестров компонентов.
|
|
141
|
+
3. Добавить автоматические проверки целостности render graph (минимум smoke/contract test).
|
|
142
|
+
4. Расширить Storybook-документацию: явно показывать host/remote-binding не только для `UiSelect`.
|
|
143
|
+
5. После стабилизации перейти к автоматизации registry/provider (кодогенерация) как к следующему этапу эволюции.
|
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,15 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
3
|
|
|
4
|
+
## [0.9.8](https://github.com/retailcrm/embed-ui/compare/v0.9.7...v0.9.8) (2026-02-12)
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* **v1-components:** UiSelect, UiMenuItem components added ([7980397](https://github.com/retailcrm/embed-ui/commit/7980397c83c20bf92453b5c9b2ba3eda4f6da93f))
|
|
9
|
+
|
|
10
|
+
### Bug Fixes
|
|
11
|
+
|
|
12
|
+
* CreateRoot host registry was synchronized with v1-components render graph ([eaa04a8](https://github.com/retailcrm/embed-ui/commit/eaa04a88712116ffeb7c4af047d419abff4e8847))
|
|
4
13
|
## [0.9.7](https://github.com/retailcrm/embed-ui/compare/v0.9.6...v0.9.7) (2026-01-13)
|
|
5
14
|
|
|
6
15
|
### Bug Fixes
|
package/Makefile
CHANGED
|
@@ -39,6 +39,21 @@ else
|
|
|
39
39
|
$(YARN) test
|
|
40
40
|
endif
|
|
41
41
|
|
|
42
|
+
.PHONY: tests-typecheck-contexts
|
|
43
|
+
tests-typecheck-contexts: ## Runs typecheck tests (test-d.ts) for v1-contexts
|
|
44
|
+
$(TARGET_HEADER)
|
|
45
|
+
ifdef cli
|
|
46
|
+
$(YARN) vitest run -c packages/v1-contexts/vitest.config.ts --typecheck.only --typecheck.checker tsc --typecheck.tsconfig packages/v1-contexts/tsconfig.json $(cli)
|
|
47
|
+
else
|
|
48
|
+
$(YARN) vitest run -c packages/v1-contexts/vitest.config.ts --typecheck.only --typecheck.checker tsc --typecheck.tsconfig packages/v1-contexts/tsconfig.json
|
|
49
|
+
endif
|
|
50
|
+
|
|
51
|
+
.PHONY: tests-typecheck-v1-contexts
|
|
52
|
+
tests-typecheck-v1-contexts: tests-typecheck-contexts ## Alias for tests-typecheck-contexts
|
|
53
|
+
|
|
54
|
+
.PHONY: tests-typecheck
|
|
55
|
+
tests-typecheck: tests-typecheck-contexts ## Runs typecheck tests (currently v1-contexts)
|
|
56
|
+
|
|
42
57
|
.PHONY: help
|
|
43
58
|
help: ## Calls recipes list
|
|
44
59
|
@cat $(MAKEFILE_LIST) | grep -e "^[a-zA-Z_\-]*: *.*## *" | awk '\
|
package/dist/index.cjs
CHANGED
|
@@ -82,6 +82,8 @@ const createRoot = async (channel) => {
|
|
|
82
82
|
"UiImage",
|
|
83
83
|
"UiLink",
|
|
84
84
|
"UiLoader",
|
|
85
|
+
"UiMenuItem",
|
|
86
|
+
"UiMenuItemGroup",
|
|
85
87
|
"UiModalSidebar",
|
|
86
88
|
"UiModalWindow",
|
|
87
89
|
"UiModalWindowSurface",
|
|
@@ -90,6 +92,8 @@ const createRoot = async (channel) => {
|
|
|
90
92
|
"UiPopperTarget",
|
|
91
93
|
"UiRadio",
|
|
92
94
|
"UiScrollBox",
|
|
95
|
+
"UiSelectPopper",
|
|
96
|
+
"UiSelectTrigger",
|
|
93
97
|
"UiTag",
|
|
94
98
|
"UiTextbox",
|
|
95
99
|
"UiToolbarButton",
|
package/dist/index.mjs
CHANGED
|
@@ -81,6 +81,8 @@ const createRoot = async (channel) => {
|
|
|
81
81
|
"UiImage",
|
|
82
82
|
"UiLink",
|
|
83
83
|
"UiLoader",
|
|
84
|
+
"UiMenuItem",
|
|
85
|
+
"UiMenuItemGroup",
|
|
84
86
|
"UiModalSidebar",
|
|
85
87
|
"UiModalWindow",
|
|
86
88
|
"UiModalWindowSurface",
|
|
@@ -89,6 +91,8 @@ const createRoot = async (channel) => {
|
|
|
89
91
|
"UiPopperTarget",
|
|
90
92
|
"UiRadio",
|
|
91
93
|
"UiScrollBox",
|
|
94
|
+
"UiSelectPopper",
|
|
95
|
+
"UiSelectTrigger",
|
|
92
96
|
"UiTag",
|
|
93
97
|
"UiTextbox",
|
|
94
98
|
"UiToolbarButton",
|
package/dist/meta.json
CHANGED
|
@@ -888,7 +888,7 @@
|
|
|
888
888
|
"description": {
|
|
889
889
|
"en-GB": "The order ID in the external source system",
|
|
890
890
|
"es-ES": "El ID del pedido en el sistema de origen externo",
|
|
891
|
-
"ru-RU": "
|
|
891
|
+
"ru-RU": "Идентификатор заказа во внешней системе источника"
|
|
892
892
|
},
|
|
893
893
|
"readonly": true
|
|
894
894
|
},
|
package/index.d.ts
CHANGED
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@retailcrm/embed-ui",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "0.9.
|
|
4
|
+
"version": "0.9.8",
|
|
5
5
|
"description": "API and components for creating RetailCRM UI extensions",
|
|
6
6
|
"repository": "git@github.com:retailcrm/embed-ui.git",
|
|
7
7
|
"author": "RetailDriverLLC <integration@retailcrm.ru>",
|
|
@@ -40,15 +40,15 @@
|
|
|
40
40
|
"@omnicajs/symfony-router": "^1.0.0",
|
|
41
41
|
"@omnicajs/vue-remote": "^0.2.8",
|
|
42
42
|
"@remote-ui/rpc": "^1.4.5",
|
|
43
|
-
"@retailcrm/embed-ui-v1-contexts": "^0.9.
|
|
44
|
-
"@retailcrm/embed-ui-v1-types": "^0.9.
|
|
43
|
+
"@retailcrm/embed-ui-v1-contexts": "^0.9.8",
|
|
44
|
+
"@retailcrm/embed-ui-v1-types": "^0.9.8"
|
|
45
45
|
},
|
|
46
46
|
"devDependencies": {
|
|
47
47
|
"@eslint/eslintrc": "^3.3.3",
|
|
48
48
|
"@eslint/js": "^9.39.1",
|
|
49
49
|
"@modulify/git-toolkit": "^0.0.2",
|
|
50
50
|
"@modulify/pkg": "^1.0.1",
|
|
51
|
-
"@retailcrm/embed-ui-v1-testing": "^0.9.
|
|
51
|
+
"@retailcrm/embed-ui-v1-testing": "^0.9.8",
|
|
52
52
|
"@types/git-semver-tags": "^7.0.0",
|
|
53
53
|
"@types/node": "^22.19.2",
|
|
54
54
|
"@types/semver": "^7.7.1",
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: commit-workflow
|
|
3
|
+
description: Use this skill when creating commits in this repository. It standardizes commit splitting, Conventional Commit type/scope selection, and English commit messages with workspace-folder scopes.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Commit Workflow
|
|
7
|
+
|
|
8
|
+
## When To Use
|
|
9
|
+
Use this skill when the user asks to:
|
|
10
|
+
- create one or more commits;
|
|
11
|
+
- split changes into multiple commits;
|
|
12
|
+
- choose commit message types/scopes;
|
|
13
|
+
- validate commit format before committing.
|
|
14
|
+
|
|
15
|
+
## Source Of Truth
|
|
16
|
+
- `AGENTS.md`
|
|
17
|
+
- root `package.json` (`workspaces: ["packages/*"]`)
|
|
18
|
+
- actual workspace folders under `packages/`
|
|
19
|
+
|
|
20
|
+
## Required Rules
|
|
21
|
+
- Commit format: Conventional Commits.
|
|
22
|
+
- Commit message language: English.
|
|
23
|
+
- Allowed types: `feat`, `fix`, `build`, `ci`, `perf`, `docs`, `refactor`, `style`, `test`, `chore`.
|
|
24
|
+
- Scope rule for workspace changes: use workspace folder name (not npm package name).
|
|
25
|
+
- Current workspace scopes:
|
|
26
|
+
- `v1-components`
|
|
27
|
+
- `v1-contexts`
|
|
28
|
+
- `v1-testing`
|
|
29
|
+
- `v1-types`
|
|
30
|
+
- For root/global repository changes, scope may be omitted.
|
|
31
|
+
- Split commits by logical intent.
|
|
32
|
+
- If one change affects multiple workspaces, split by workspace unless user explicitly asks to combine.
|
|
33
|
+
- Keep subject concise and factual.
|
|
34
|
+
- Start subject description with an uppercase letter.
|
|
35
|
+
- Mention affected component(s) or area in subject description when applicable.
|
|
36
|
+
- Subject should describe completed change in past tense.
|
|
37
|
+
- Prefer passive voice for changelog-friendly phrasing.
|
|
38
|
+
- Do not amend/rewrite history unless explicitly requested.
|
|
39
|
+
|
|
40
|
+
## Workflow
|
|
41
|
+
1. Inspect pending changes:
|
|
42
|
+
```bash
|
|
43
|
+
git status --short
|
|
44
|
+
git diff
|
|
45
|
+
```
|
|
46
|
+
2. Map changed files to workspace folders (`packages/<workspace>/...`) or root/global files.
|
|
47
|
+
3. Group changes into commit batches by logical intent and workspace boundary.
|
|
48
|
+
4. Choose commit header:
|
|
49
|
+
```text
|
|
50
|
+
<type>(<workspace-scope>): <short english summary>
|
|
51
|
+
```
|
|
52
|
+
or for global changes:
|
|
53
|
+
```text
|
|
54
|
+
<type>: <short english summary>
|
|
55
|
+
```
|
|
56
|
+
5. Stage only files for the current batch:
|
|
57
|
+
```bash
|
|
58
|
+
git add <files>
|
|
59
|
+
```
|
|
60
|
+
6. Create commit (non-interactive):
|
|
61
|
+
```bash
|
|
62
|
+
git commit -m "<type>(<scope>): <summary>"
|
|
63
|
+
```
|
|
64
|
+
7. Verify result:
|
|
65
|
+
```bash
|
|
66
|
+
git show --name-status --oneline -n 1
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Practical Patterns
|
|
70
|
+
- Workspace feature:
|
|
71
|
+
`feat(v1-components): UiSelect searchable select option groups added`
|
|
72
|
+
- Workspace fix:
|
|
73
|
+
`fix(v1-contexts): OrderContext missing order id handling corrected`
|
|
74
|
+
- Global docs update:
|
|
75
|
+
`docs: AGENTS repository agent instructions updated`
|
|
76
|
+
- Root tooling/config change:
|
|
77
|
+
`chore: Root yarn workspace build flow updated`
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sync-remote-host-registry
|
|
3
|
+
description: Use this skill when updating remote-to-host component registries (for example createRoot component lists) to keep them aligned with the actual render graph instead of naive host export parity.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Sync Remote Host Registry
|
|
7
|
+
|
|
8
|
+
## When To Use
|
|
9
|
+
Use this skill when:
|
|
10
|
+
- updating `createRoot(..., { components: [...] })` lists;
|
|
11
|
+
- updating Storybook provider/receiver setups for remote rendering;
|
|
12
|
+
- checking whether a host component should be added to or removed from a remote render registry.
|
|
13
|
+
|
|
14
|
+
## Source Of Truth
|
|
15
|
+
- `src/index.ts` (`createRoot` in root package)
|
|
16
|
+
- `packages/v1-components/src/host.ts`
|
|
17
|
+
- `packages/v1-components/src/remote.ts`
|
|
18
|
+
- `packages/v1-components/src/remote/components/**/*`
|
|
19
|
+
- `packages/v1-components/storybook/endpoint.ts`
|
|
20
|
+
- `packages/v1-components/storybook/stories/UiSelect.stories.ts`
|
|
21
|
+
- `packages/v1-components/storybook/stories/UiSelect.remote.ts`
|
|
22
|
+
|
|
23
|
+
## Core Model
|
|
24
|
+
- `host.ts` is the catalog of available host implementations.
|
|
25
|
+
- `remote.ts` is the public remote API surface.
|
|
26
|
+
- Registries like `createRoot(...components)` must include host components that are schema-reachable from remote rendering flow.
|
|
27
|
+
- Non-1:1 mapping is valid:
|
|
28
|
+
- one remote component may render through multiple host primitives;
|
|
29
|
+
- host-only components can exist and must not be added if remote flow never emits them.
|
|
30
|
+
|
|
31
|
+
## Practical Rules
|
|
32
|
+
- Do not assume parity with `host.ts`.
|
|
33
|
+
- Include a host component if remote rendering can emit its schema in this runtime path.
|
|
34
|
+
- Exclude host-only components that are not emitted by remote instructions in this runtime path.
|
|
35
|
+
- For Storybook remote stories, provider can stay minimal and story-specific.
|
|
36
|
+
- For product/runtime `src/index.ts`, registry should cover all host schemas used by runtime remote render graph.
|
|
37
|
+
|
|
38
|
+
## Workflow
|
|
39
|
+
1. Inspect current registry and target area:
|
|
40
|
+
```bash
|
|
41
|
+
nl -ba src/index.ts | sed -n '68,120p'
|
|
42
|
+
```
|
|
43
|
+
2. Inspect host export catalog:
|
|
44
|
+
```bash
|
|
45
|
+
nl -ba packages/v1-components/src/host.ts | sed -n '1,120p'
|
|
46
|
+
```
|
|
47
|
+
3. Inspect remote public surface:
|
|
48
|
+
```bash
|
|
49
|
+
nl -ba packages/v1-components/src/remote.ts | sed -n '1,120p'
|
|
50
|
+
```
|
|
51
|
+
4. Inspect composite remote components (especially non-1:1 cases) and their internal parts.
|
|
52
|
+
5. Update registry by render-graph reachability, not by export parity.
|
|
53
|
+
6. Validate:
|
|
54
|
+
```bash
|
|
55
|
+
yarn eslint src/index.ts
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Review Checklist
|
|
59
|
+
- Every newly added registry item is justified by remote render flow.
|
|
60
|
+
- Removed items are proven host-only for this runtime path.
|
|
61
|
+
- Composite components (like select) are checked through their internal remote parts.
|
|
62
|
+
- Storybook-specific minimal providers are not blindly copied into runtime and vice versa.
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: yarn-lock-conflict-resolution
|
|
3
|
+
description: Use this skill when resolving merge/rebase conflicts in yarn.lock. It standardizes taking yarn.lock from the target branch, reconciling it with yarn install, and reusing a successful resolution across repeated conflict rounds.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Yarn.lock Conflict Resolution
|
|
7
|
+
|
|
8
|
+
## When To Use
|
|
9
|
+
Use this skill when:
|
|
10
|
+
- `yarn.lock` has merge/rebase conflicts;
|
|
11
|
+
- conflict resolution should be repeatable and low-risk;
|
|
12
|
+
- the same conflict appears in multiple rounds of one rebase/merge sequence.
|
|
13
|
+
|
|
14
|
+
## Source Of Truth Policy
|
|
15
|
+
- Rebase: take `yarn.lock` from the branch you rebase onto.
|
|
16
|
+
- Merge: take `yarn.lock` from `HEAD` (current target branch).
|
|
17
|
+
- After taking baseline, run `yarn install` to reconcile lock metadata with current manifests.
|
|
18
|
+
|
|
19
|
+
## Required Rules
|
|
20
|
+
- Do not manually resolve conflict markers inside `yarn.lock`.
|
|
21
|
+
- Replace `yarn.lock` completely from the selected baseline.
|
|
22
|
+
- Reuse previous successful resolution for repeated rounds in the same sequence.
|
|
23
|
+
- If dependency updates were intentional in the rebased commit, replay dependency commands after conflict resolution.
|
|
24
|
+
|
|
25
|
+
## Workflow
|
|
26
|
+
1. Ensure conflict exists:
|
|
27
|
+
```bash
|
|
28
|
+
git status --short
|
|
29
|
+
```
|
|
30
|
+
2. (Optional) Ensure Yarn config exists:
|
|
31
|
+
```bash
|
|
32
|
+
make .yarnrc.yml
|
|
33
|
+
```
|
|
34
|
+
3. Resolve first conflict round for rebase:
|
|
35
|
+
```bash
|
|
36
|
+
ONTO=$(cat .git/rebase-merge/onto 2>/dev/null || cat .git/rebase-apply/onto)
|
|
37
|
+
git show "$ONTO:yarn.lock" > yarn.lock
|
|
38
|
+
yarn install
|
|
39
|
+
git add yarn.lock
|
|
40
|
+
cp yarn.lock .git/yarn-lock-resolution-base
|
|
41
|
+
```
|
|
42
|
+
4. Resolve first conflict round for merge:
|
|
43
|
+
```bash
|
|
44
|
+
git show "HEAD:yarn.lock" > yarn.lock
|
|
45
|
+
yarn install
|
|
46
|
+
git add yarn.lock
|
|
47
|
+
cp yarn.lock .git/yarn-lock-resolution-base
|
|
48
|
+
```
|
|
49
|
+
5. Resolve repeated rounds in the same sequence:
|
|
50
|
+
```bash
|
|
51
|
+
cp .git/yarn-lock-resolution-base yarn.lock
|
|
52
|
+
yarn install
|
|
53
|
+
git add yarn.lock
|
|
54
|
+
cp yarn.lock .git/yarn-lock-resolution-base
|
|
55
|
+
```
|
|
56
|
+
6. Continue operation:
|
|
57
|
+
```bash
|
|
58
|
+
git rebase --continue
|
|
59
|
+
# or
|
|
60
|
+
git merge --continue
|
|
61
|
+
```
|
|
62
|
+
7. Cleanup after finish:
|
|
63
|
+
```bash
|
|
64
|
+
rm -f .git/yarn-lock-resolution-base
|
|
65
|
+
```
|
|
66
|
+
8. If dependency updates must be replayed, run original dependency command and commit lockfile update with an English Conventional Commit message, for example:
|
|
67
|
+
```bash
|
|
68
|
+
yarn up <packages>
|
|
69
|
+
git add yarn.lock
|
|
70
|
+
git commit -m "chore: refresh yarn.lock"
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Validation
|
|
74
|
+
- `git status --short` has no unresolved conflicts for `yarn.lock`.
|
|
75
|
+
- `yarn.lock` is staged before `--continue`.
|
|
76
|
+
- Resolution follows source-of-truth policy above.
|