@retailcrm/embed-ui-v1-components 0.9.14 → 0.9.15

package/AGENTS.md

@@ -0,0 +1,126 @@
+# AGENTS.md
+
+## Purpose
+
+This file is for AI assistants and automation that use the built package
+`@retailcrm/embed-ui-v1-components` in application code.
+
+It is not a contributor guide for editing the internal source of this workspace.
+Treat this file as usage guidance for the published API.
+
+## What This Package Is
+
+- Package: `@retailcrm/embed-ui-v1-components`
+- Role: UI component library for RetailCRM JS extensions
+- Framework: Vue 3
+- Main consumer entrypoint: `@retailcrm/embed-ui-v1-components/remote`
+
+This package exposes declarative UI primitives that are rendered by RetailCRM host runtime.
+
+## How To Import
+
+- For extension UI code, import from `@retailcrm/embed-ui-v1-components/remote`.
+- For icons and static assets, import from `@retailcrm/embed-ui-v1-components/assets/...`.
+- Do not import from package-internal files such as `dist/*` or internal workspace files when writing extension code.
+- Do not recommend `@retailcrm/embed-ui-v1-components/host` unless the task is explicitly about CRM host internals.
+
+## Mental Model
+
+- `remote` is the public API for extension authors.
+- Components from `remote` do not represent a standalone design system outside RetailCRM.
+- Extension code describes UI declaratively, and the CRM host side interprets and renders it.
+- Because of this architecture, prefer documented public props and slots over assumptions based on internal implementation.
+
+## Safe Default Recommendation
+
+When building UI in an extension, start with imports like:
+
+```ts
+import {
+  UiButton,
+  UiField,
+  UiPageHeader,
+  UiSelect,
+  UiTextbox,
+} from '@retailcrm/embed-ui-v1-components/remote'
+```
+
+## Public API Areas
+
+Commonly used exports from `remote` include:
+
+- form controls:
+  `UiTextbox`, `UiCheckbox`, `UiRadio`, `UiSwitch`, `UiSlider`, `UiNumberStepper`
+- selection and date controls:
+  `UiSelect`, `UiSelectOption`, `UiSelectOptionGroup`, `UiDatePicker`, `UiTimePicker`, `UiCalendar`
+- layout and structure:
+  `UiField`, `UiPageHeader`, `UiCollapse`, `UiCollapseBox`, `UiScrollBox`
+- actions and links:
+  `UiButton`, `UiAddButton`, `UiCopyButton`, `UiToolbarButton`, `UiToolbarLink`, `UiLink`
+- feedback and overlays:
+  `UiAlert`, `UiInfobox`, `UiError`, `UiLoader`, `UiTooltip`, `UiModalWindow`, `UiModalSidebar`
+- content and data display:
+  `UiAvatar`, `UiAvatarList`, `UiDate`, `UiImage`, `UiTag`, `UiTable`, `UiTableColumn`, `UiYandexMap`
+- helpers:
+  `usePreview`, `ImageWorkersKey`, `formatDate`, `formatDateTime`, `formatTime`
+
+## Usage Rules
+
+- Prefer package public exports over reimplementing CRM-styled controls manually.
+- Match component choice to semantics:
+  use `UiField` for labeled form controls, `UiAlert` for state messages, `UiPageHeader` for page-level headings.
+- Keep imports on the public package boundary.
+- If you are unsure whether something is public, assume only exports from `remote` and `assets/*` are safe for consumer code.
+- If a needed capability is missing from the public API, say that clearly instead of suggesting internal imports.
+
+## What To Avoid
+
+- Do not import from `@retailcrm/embed-ui-v1-components/host` in normal extension code.
+- Do not rely on internal file paths from this repository.
+- Do not treat Storybook examples or internal source layout as stable runtime API.
+- Do not assume every host-side component is available to extension authors.
+
+## Example
+
+```vue
+<template>
+  <UiPageHeader
+    title="История заказа"
+    description="Последние изменения и служебные действия"
+  />
+
+  <UiField id="comment" label="Комментарий">
+    <UiTextbox v-model="comment" placeholder="Введите текст" />
+  </UiField>
+
+  <UiButton @click="save">
+    Сохранить
+  </UiButton>
+</template>
+
+<script lang="ts" setup>
+import { ref } from 'vue'
+
+import {
+  UiButton,
+  UiField,
+  UiPageHeader,
+  UiTextbox,
+} from '@retailcrm/embed-ui-v1-components/remote'
+
+const comment = ref('')
+
+const save = () => {}
+</script>
+```
+
+## If You Need More Context
+
+- Package README:
+  [`./README.md`](./README.md)
+- Human-oriented package docs:
+  [`./docs/README.md`](./docs/README.md)
+- Machine-oriented package summary:
+  [`./docs/AI.md`](./docs/AI.md)
+- Component profiles:
+  [`./docs/PROFILES.md`](./docs/PROFILES.md)

package/README.md

@@ -41,3 +41,27 @@ import { UiButton } from '@retailcrm/embed-ui-v1-components/remote'
 интерфейс. Библиотека также содержит `@retailcrm/embed-ui-v1-components/host` – набор компонентов,
 который будет использовать CRM при интерпретации инструкций от расширений. **_Не используйте_** host компоненты
 как часть кода расширения.
+
+## Документация пакета
+
+Дополнительные материалы по пакету находятся в `docs/`:
+
+- [`docs/README.md`](./docs/README.md) — обзор пакета и правил использования.
+- [`docs/COMPONENTS.md`](./docs/COMPONENTS.md) — карта публичных компонентов.
+- [`docs/AI.md`](./docs/AI.md) — контекст для ИИ и автоматизаций.
+- [`docs/PROFILES.md`](./docs/PROFILES.md) — AI-friendly YAML-профили компонентов.
+- [`docs/FORMAT.md`](./docs/FORMAT.md) — формат описания компонента для AI-агентов.
+
+## AI и инициализация `AGENTS.md`
+
+После установки пакет показывает подсказку, что внутри есть AI-заметки и YAML-профили компонентов.
+
+Если в целевом проекте еще нет `AGENTS.md`, можно сгенерировать стартовый файл командой:
+
+```bash
+npx @retailcrm/embed-ui-v1-components init-agents
+```
+
+Если `AGENTS.md` уже существует, команда допишет в конец инструкции для
+`@retailcrm/embed-ui-v1-components`, если такого блока там еще нет. С `--force`
+можно обновить уже существующий блок пакета.

package/assets/stylesheets/palette.less

@@ -11,7 +11,8 @@
 @red-800: #932121;
 @red-900: #932121;
 
-@red-transparent: rgba(255, 83, 83, 0.1);
+@red-translucent: rgba(255, 83, 83, 0.1);
+@red-transparent: @red-translucent;
 
 /* Blue */
 @blue-100: #EDF4FF;
@@ -24,7 +25,8 @@
 @blue-800: #0033A2;
 @blue-900: #00228C;
 
-@blue-transparent: rgba(0, 94, 235, 0.12);
+@blue-translucent: rgba(0, 94, 235, 0.12);
+@blue-transparent: @blue-translucent;
 
 /* Yellow */
 @yellow-100: #FFF9F0;
@@ -37,7 +39,8 @@
 @yellow-800: #BC6B01;
 @yellow-900: #965601;
 
-@yellow-transparent: rgba(254, 165, 48, 0.12);
+@yellow-translucent: rgba(254, 165, 48, 0.12);
+@yellow-transparent: @yellow-translucent;
 
 /* Green */
 @green-100: #D8F8EE;
@@ -50,7 +53,8 @@
 @green-800: #168561;
 @green-900: #106349;
 
-@green-transparent: rgba(34, 201, 147, 0.16);
+@green-translucent: rgba(34, 201, 147, 0.16);
+@green-transparent: @green-translucent;
 
 /* Purple */
 @purple-100: #E5DBF8;
@@ -63,7 +67,8 @@
 @purple-800: #371F7C;
 @purple-900: #2D1A68;
 
-@purple-transparent: rgba(101, 40, 215, 0.12);
+@purple-translucent: rgba(101, 40, 215, 0.12);
+@purple-transparent: @purple-translucent;
 
 /* Black */
 @black-100: #323976;
@@ -85,4 +90,4 @@
 @grey-600: #C7CDD4;
 @grey-700: #AFB9C3;
 @grey-800: #8A96A6;
-@grey-900: #636F7F;
+@grey-900: #636F7F;

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

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+const PACKAGE_NAME = '@retailcrm/embed-ui-v1-components'
+const DEFAULT_NEWLINE = '\n'
+const AGENTS_SECTION_HEADER = '## @retailcrm/embed-ui-v1-components'
+
+const HELP_TEXT = `Usage:
+  npx ${PACKAGE_NAME} init-agents [target] [options]
+
+Options:
+  -f, --force           Replace existing package section in AGENTS.md
+  -h, --help            Show this help
+
+Examples:
+  npx ${PACKAGE_NAME} init-agents
+  npx ${PACKAGE_NAME} init-agents ./my-project
+  npx ${PACKAGE_NAME} init-agents --force
+`
+
+const parseArgs = (argv) => {
+  const options = {
+    command: null,
+    target: process.cwd(),
+    force: false,
+  }
+
+  const positionals = []
+
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index]
+
+    if (argument === '-h' || argument === '--help') {
+      console.log(HELP_TEXT)
+      process.exit(0)
+    }
+
+    if (argument === '-f' || argument === '--force') {
+      options.force = true
+      continue
+    }
+
+    if (argument.startsWith('-')) {
+      throw new Error(`Unknown option: ${argument}`)
+    }
+
+    positionals.push(argument)
+  }
+
+  if (!positionals.length) {
+    throw new Error('Command is required')
+  }
+
+  options.command = positionals[0]
+
+  if (positionals.length >= 2) {
+    options.target = path.resolve(process.cwd(), positionals[1])
+  }
+
+  if (positionals.length > 2) {
+    throw new Error('Too many positional arguments')
+  }
+
+  return options
+}
+
+const createAgentsTemplate = () => {
+  return `# AGENTS.md
+
+${AGENTS_SECTION_HEADER}
+
+When working with \`${PACKAGE_NAME}\` in this project:
+
+1. Read \`./node_modules/${PACKAGE_NAME}/docs/AI.md\`.
+2. Then read \`./node_modules/${PACKAGE_NAME}/docs/COMPONENTS.md\`.
+3. Then open the relevant profile from \`./node_modules/${PACKAGE_NAME}/docs/profiles/<Component>.yml\`.
+4. Prefer those docs and profiles over guessing from internal implementation files.
+5. Import only from documented public entrypoints:
+   - \`${PACKAGE_NAME}/remote\`
+   - \`${PACKAGE_NAME}/host\`
+   - \`${PACKAGE_NAME}/assets/...\`
+6. Prefer \`${PACKAGE_NAME}/remote\` for extension UI code.
+7. Do not import from package-internal files such as \`dist/*\`, repository-only paths, or source internals.
+
+## Suggested Reading Order
+
+1. \`docs/AI.md\`
+2. \`docs/COMPONENTS.md\`
+3. The relevant profile from \`docs/profiles/*.yml\`
+4. \`docs/FORMAT.md\` if you need to understand profile structure
+5. Storybook and public types only when no profile exists yet
+` + DEFAULT_NEWLINE
+}
+
+const createAgentsSection = () => {
+  return `${AGENTS_SECTION_HEADER}
+
+When working with \`${PACKAGE_NAME}\` in this project:
+
+1. Read \`./node_modules/${PACKAGE_NAME}/docs/AI.md\`.
+2. Then read \`./node_modules/${PACKAGE_NAME}/docs/COMPONENTS.md\`.
+3. Then open the relevant profile from \`./node_modules/${PACKAGE_NAME}/docs/profiles/<Component>.yml\`.
+4. Prefer those docs and profiles over guessing from internal implementation files.
+5. Import only from documented public entrypoints:
+   - \`${PACKAGE_NAME}/remote\`
+   - \`${PACKAGE_NAME}/host\`
+   - \`${PACKAGE_NAME}/assets/...\`
+6. Prefer \`${PACKAGE_NAME}/remote\` for extension UI code.
+7. Do not import from package-internal files such as \`dist/*\`, repository-only paths, or source internals.
+
+## Suggested Reading Order
+
+1. \`docs/AI.md\`
+2. \`docs/COMPONENTS.md\`
+3. The relevant profile from \`docs/profiles/*.yml\`
+4. \`docs/FORMAT.md\` if you need to understand profile structure
+5. Storybook and public types only when no profile exists yet
+`
+}
+
+const hasPackageSection = (content) => content.includes(AGENTS_SECTION_HEADER)
+
+const appendSection = (content, section) => {
+  const trimmed = content.replace(/\s+$/u, '')
+
+  if (!trimmed.length) {
+    return `${section}${DEFAULT_NEWLINE}`
+  }
+
+  return `${trimmed}${DEFAULT_NEWLINE}${DEFAULT_NEWLINE}${section}${DEFAULT_NEWLINE}`
+}
+
+const replaceSection = (content, section) => {
+  const escapedHeader = AGENTS_SECTION_HEADER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const sectionPattern = new RegExp(`${escapedHeader}[\\s\\S]*?(?=\\n##\\s|$)`, 'u')
+
+  if (!sectionPattern.test(content)) {
+    return appendSection(content, section)
+  }
+
+  return content
+    .replace(sectionPattern, section.trimEnd())
+    .replace(/\s+$/u, '') + DEFAULT_NEWLINE
+}
+
+const initAgents = (target, force) => {
+  if (!fs.existsSync(target)) {
+    throw new Error(`Target path does not exist: ${target}`)
+  }
+
+  const stat = fs.statSync(target)
+
+  if (!stat.isDirectory()) {
+    throw new Error(`Target path is not a directory: ${target}`)
+  }
+
+  const agentsPath = path.join(target, 'AGENTS.md')
+  const section = createAgentsSection()
+
+  if (!fs.existsSync(agentsPath)) {
+    fs.writeFileSync(agentsPath, createAgentsTemplate(), 'utf8')
+
+    console.log(`AGENTS.md was created at ${agentsPath}`)
+    console.log('Next step: review it and adjust project-specific rules if needed.')
+    return
+  }
+
+  const currentContent = fs.readFileSync(agentsPath, 'utf8')
+
+  if (force) {
+    fs.writeFileSync(agentsPath, replaceSection(currentContent, section), 'utf8')
+    console.log(`AGENTS.md was updated at ${agentsPath}`)
+    console.log(`The ${PACKAGE_NAME} section was refreshed.`)
+    return
+  }
+
+  if (hasPackageSection(currentContent)) {
+    console.log(`AGENTS.md already contains a ${PACKAGE_NAME} section at ${agentsPath}`)
+    console.log('Nothing was changed. Re-run with --force to refresh that section.')
+    return
+  }
+
+  fs.writeFileSync(agentsPath, appendSection(currentContent, section), 'utf8')
+
+  console.log(`AGENTS.md was updated at ${agentsPath}`)
+  console.log(`The ${PACKAGE_NAME} instructions were appended to the end of the file.`)
+}
+
+const main = () => {
+  try {
+    const options = parseArgs(process.argv.slice(2))
+
+    if (options.command !== 'init-agents') {
+      throw new Error(`Unknown command: ${options.command}`)
+    }
+
+    initAgents(options.target, options.force)
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    console.error('')
+    console.error(HELP_TEXT)
+    process.exit(1)
+  }
+}
+
+main()

package/bin/postinstall.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url'
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+const PACKAGE_NAME = '@retailcrm/embed-ui-v1-components'
+
+const currentFile = fileURLToPath(import.meta.url)
+const packageRoot = path.resolve(path.dirname(currentFile), '..')
+
+const isInstalledFromNodeModules = packageRoot.includes(`${path.sep}node_modules${path.sep}`)
+
+if (!isInstalledFromNodeModules) {
+  process.exit(0)
+}
+
+const targetRoot = process.env.INIT_CWD
+
+if (!targetRoot) {
+  process.exit(0)
+}
+
+const agentsPath = path.join(targetRoot, 'AGENTS.md')
+const hasAgentsFile = fs.existsSync(agentsPath)
+
+console.log('')
+console.log(`[${PACKAGE_NAME}] AI docs are available in node_modules/${PACKAGE_NAME}/docs`)
+console.log(`[${PACKAGE_NAME}] Start with docs/AI.md, docs/COMPONENTS.md, and docs/profiles/*.yml`)
+
+if (!hasAgentsFile) {
+  console.log(`[${PACKAGE_NAME}] To scaffold AGENTS.md for this project, run:`)
+  console.log(`  npx ${PACKAGE_NAME} init-agents`)
+} else {
+  console.log(`[${PACKAGE_NAME}] AGENTS.md already exists in this project, so no scaffold was created automatically`)
+}