@retailcrm/embed-ui-v1-components 0.9.19 → 0.9.22-alpha.1

package/AGENTS.md

@@ -77,7 +77,7 @@ Commonly used exports from `remote` include:
 
 - 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 treat examples or internal source layout as stable runtime API.
 - Do not assume every host-side component is available to extension authors.
 
 ## Example
@@ -122,5 +122,13 @@ const save = () => {}
   [`./docs/README.md`](./docs/README.md)
 - Machine-oriented package summary:
   [`./docs/AI.md`](./docs/AI.md)
+- Page composition guidelines:
+  [`./docs/profiles/pages`](./docs/profiles/pages)
 - Component profiles:
   [`./docs/PROFILES.md`](./docs/PROFILES.md)
+
+For table, catalog, registry, journal, or search-result screens, read [`./docs/AI.md`](./docs/AI.md)
+and [`./docs/profiles/pages/EntityListPage.yml`](./docs/profiles/pages/EntityListPage.yml), then check the
+`UiTable` and `UiLink` profiles before generating code. Put filters above the table, persist
+filters and pagination in GET query parameters when routing exists, and set `size="small"` on
+`UiLink` inside table cells by default.

package/README.md

@@ -46,15 +46,18 @@ import { UiButton } from '@retailcrm/embed-ui-v1-components/remote'
 
 Дополнительные материалы по пакету находятся в `docs/`:
 
+- [`AGENTS.md`](./AGENTS.md) — инструкции для AI-агентов, использующих пакет в целевом проекте.
 - [`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/PROFILES.md`](./docs/PROFILES.md) — AI-friendly YAML-профили компонентов и страниц.
 - [`docs/FORMAT.md`](./docs/FORMAT.md) — формат описания компонента для AI-агентов.
+- [`docs/profiles/pages`](./docs/profiles/pages) — YAML-профили страниц, модалок, шторок, фильтров и таблиц.
 
 ## AI и инициализация `AGENTS.md`
 
-После установки пакет показывает подсказку, что внутри есть AI-заметки и YAML-профили компонентов.
+После установки пакет показывает подсказку, что внутри есть `README.md`, `AGENTS.md`,
+AI-заметки и YAML-профили компонентов и страниц.
 
 Если в целевом проекте еще нет `AGENTS.md`, можно сгенерировать стартовый файл командой:
 

package/assets/sprites/actions/add-square-outlined.svg

@@ -0,0 +1,8 @@
+<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+        fill-rule="evenodd"
+        clip-rule="evenodd"
+        fill="currentColor"
+        d="M19 3H5C3.89543 3 3 3.89543 3 5V19C3 20.1046 3.89543 21 5 21H19C20.1046 21 21 20.1046 21 19V5C21 3.89543 20.1046 3 19 3ZM19 19H5V5H19V19ZM11 13H8.5C8.22386 13 8 12.7761 8 12.5V11.5C8 11.2239 8.22386 11 8.5 11H11V8.5C11 8.22386 11.2239 8 11.5 8H12.5C12.7761 8 13 8.22386 13 8.5V11H15.5C15.7761 11 16 11.2239 16 11.5V12.5C16 12.7761 15.7761 13 15.5 13H13V15.5C13 15.7761 12.7761 16 12.5 16H11.5C11.2239 16 11 15.7761 11 15.5V13Z"
+    />
+</svg>

package/assets/sprites/actions/drag.svg

@@ -0,0 +1,8 @@
+<svg viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg" >
+    <path
+        d="M7.4987 6.66683C8.41917 6.66683 9.16536 5.92064 9.16536 5.00016C9.16536 4.07969 8.41917 3.3335 7.4987 3.3335C6.57822 3.3335 5.83203 4.07969 5.83203 5.00016C5.83203 5.92064 6.57822 6.66683 7.4987 6.66683ZM5.83203 10.0002C5.83203 9.07969 6.57822 8.3335 7.4987 8.3335C8.41917 8.3335 9.16536 9.07969 9.16536 10.0002C9.16536 10.9206 8.41917 11.6668 7.4987 11.6668C6.57822 11.6668 5.83203 10.9206 5.83203 10.0002ZM7.4987 13.3335C6.57822 13.3335 5.83203 14.0797 5.83203 15.0002C5.83203 15.9206 6.57822 16.6668 7.4987 16.6668C8.41917 16.6668 9.16536 15.9206 9.16536 15.0002C9.16536 14.0797 8.41917 13.3335 7.4987 13.3335ZM14.1654 5.00016C14.1654 5.92064 13.4192 6.66683 12.4987 6.66683C11.5782 6.66683 10.832 5.92064 10.832 5.00016C10.832 4.07969 11.5782 3.3335 12.4987 3.3335C13.4192 3.3335 14.1654 4.07969 14.1654 5.00016ZM12.4987 8.3335C11.5782 8.3335 10.832 9.07969 10.832 10.0002C10.832 10.9206 11.5782 11.6668 12.4987 11.6668C13.4192 11.6668 14.1654 10.9206 14.1654 10.0002C14.1654 9.07969 13.4192 8.3335 12.4987 8.3335ZM10.832 15.0002C10.832 14.0797 11.5782 13.3335 12.4987 13.3335C13.4192 13.3335 14.1654 14.0797 14.1654 15.0002C14.1654 15.9206 13.4192 16.6668 12.4987 16.6668C11.5782 16.6668 10.832 15.9206 10.832 15.0002Z"
+        fill="currentColor"
+        fill-rule="evenodd"
+        clip-rule="evenodd"
+    />
+</svg>

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { fileURLToPath } from 'node:url'
 import fs from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
@@ -7,6 +8,8 @@ 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 AGENTS_SECTION_START = '<!-- embed-ui-agents:start -->'
+const AGENTS_SECTION_END = '<!-- embed-ui-agents:end -->'
 
 const HELP_TEXT = `Usage:
   npx ${PACKAGE_NAME} init-agents [target] [options]
@@ -21,6 +24,136 @@ Examples:
   npx ${PACKAGE_NAME} init-agents --force
 `
 
+const toPosixPath = (value) => value.split(path.sep).join('/')
+
+const withDotPrefix = (value) => {
+  if (!value || value === '.') {
+    return '.'
+  }
+
+  return value.startsWith('.') ? value : `./${value}`
+}
+
+const isPackageRoot = (directory) => {
+  const packageJsonPath = path.join(directory, 'package.json')
+
+  if (!fs.existsSync(packageJsonPath)) {
+    return false
+  }
+
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+
+    return packageJson.name === PACKAGE_NAME
+  } catch {
+    return false
+  }
+}
+
+const isInsideDirectory = (parent, child) => {
+  const relativePath = path.relative(parent, child)
+
+  return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath))
+}
+
+const addNestedPackageCandidates = (start, addCandidate) => {
+  const packagePath = path.join('node_modules', ...PACKAGE_NAME.split('/'))
+  const ignoredDirectories = new Set(['.git', '.yarn', 'dist', 'node_modules'])
+  const queue = [path.resolve(start)]
+  const seen = new Set(queue)
+
+  for (let index = 0; index < queue.length; index++) {
+    const current = queue[index]
+
+    addCandidate(path.join(current, packagePath))
+
+    let entries = []
+
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true })
+    } catch {
+      continue
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || ignoredDirectories.has(entry.name)) {
+        continue
+      }
+
+      const next = path.join(current, entry.name)
+
+      if (!seen.has(next)) {
+        seen.add(next)
+        queue.push(next)
+      }
+    }
+  }
+}
+
+const getCurrentPackageRoot = () => {
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+  return isPackageRoot(packageRoot) ? packageRoot : null
+}
+
+const findPackageRoot = (target) => {
+  const candidates = []
+  const seen = new Set()
+
+  const addCandidate = (candidate) => {
+    const resolved = path.resolve(candidate)
+
+    if (!seen.has(resolved)) {
+      seen.add(resolved)
+      candidates.push(resolved)
+    }
+  }
+
+  const addNodeModulesCandidates = (start) => {
+    const packagePath = path.join('node_modules', ...PACKAGE_NAME.split('/'))
+    let current = path.resolve(start)
+
+    while (true) {
+      addCandidate(path.join(current, packagePath))
+
+      const parent = path.dirname(current)
+
+      if (parent === current) {
+        break
+      }
+
+      current = parent
+    }
+  }
+
+  addCandidate(target)
+  addNodeModulesCandidates(target)
+  addNestedPackageCandidates(target, addCandidate)
+
+  const currentPackageRoot = getCurrentPackageRoot()
+
+  if (currentPackageRoot && isInsideDirectory(target, currentPackageRoot)) {
+    addCandidate(currentPackageRoot)
+  }
+
+  const packageRoot = candidates.find(isPackageRoot)
+
+  if (!packageRoot) {
+    throw new Error(
+      `Cannot find local ${PACKAGE_NAME}. Install it in this project or run init-agents from the package workspace.`
+    )
+  }
+
+  return packageRoot
+}
+
+const createPackageDocsPath = (target) => {
+  const packageRoot = findPackageRoot(target)
+  const relativePath = path.relative(target, packageRoot)
+
+  return withDotPrefix(toPosixPath(relativePath))
+}
+
 const parseArgs = (argv) => {
   const options = {
     command: null,
@@ -67,83 +200,134 @@ const parseArgs = (argv) => {
   return options
 }
 
-const createAgentsTemplate = () => {
+const createAgentsTemplate = (packageDocsPath) => {
   return `# AGENTS.md
 
+${createAgentsSection(packageDocsPath)}`
+}
+
+const createAgentsSection = (packageDocsPath) => {
+  return `${AGENTS_SECTION_START}
 ${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:
+1. Read \`${packageDocsPath}/README.md\`.
+2. Then read \`${packageDocsPath}/AGENTS.md\`.
+3. Then read \`${packageDocsPath}/docs/AI.md\`.
+4. Then read \`${packageDocsPath}/docs/COMPONENTS.md\`.
+5. Then read \`${packageDocsPath}/docs/PROFILES.md\`.
+6. Then open relevant component profiles from \`${packageDocsPath}/docs/profiles/components/*.yml\`.
+7. For complete pages, modals, sidebars, filters, tables, or settings layouts, open the relevant
+   page profile from \`${packageDocsPath}/docs/profiles/pages/*.yml\`.
+8. Prefer those docs and profiles over guessing from internal implementation files.
+9. 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.
+10. Prefer \`${PACKAGE_NAME}/remote\` for extension UI code.
+11. 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
+1. \`README.md\`
+2. \`AGENTS.md\`
+3. \`docs/AI.md\`
+4. \`docs/COMPONENTS.md\`
+5. \`docs/PROFILES.md\`
+6. The relevant component profile from \`docs/profiles/components/*.yml\`
+7. The relevant page profile from \`docs/profiles/pages/*.yml\` for full-screen or overlay composition
+8. \`docs/FORMAT.md\` if you need to understand profile structure
+9. Public type declarations only when no profile exists yet
+${AGENTS_SECTION_END}
+`
 }
 
-const createAgentsSection = () => {
-  return `${AGENTS_SECTION_HEADER}
+const findMarkedSectionRange = (content) => {
+  const start = content.indexOf(AGENTS_SECTION_START)
+  const end = content.indexOf(AGENTS_SECTION_END, start + AGENTS_SECTION_START.length)
 
-When working with \`${PACKAGE_NAME}\` in this project:
+  if (start === -1 && end === -1) {
+    return null
+  }
 
-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.
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`AGENTS.md contains incomplete ${PACKAGE_NAME} section markers`)
+  }
 
-## Suggested Reading Order
+  return {
+    start,
+    end: end + AGENTS_SECTION_END.length,
+  }
+}
 
-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 findLegacySectionRange = (content) => {
+  const escapedHeader = AGENTS_SECTION_HEADER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const headerPattern = new RegExp(`(^|\\n)${escapedHeader}(?=\\n|$)`, 'u')
+  const match = headerPattern.exec(content)
+
+  if (!match) {
+    return null
+  }
+
+  const start = match.index + match[1].length
+  const afterHeader = content.slice(start + AGENTS_SECTION_HEADER.length)
+  const nextExternalHeading = /\n## (?!Suggested Reading Order\b)[^\n]*/u.exec(afterHeader)
+
+  return {
+    start,
+    end: nextExternalHeading
+      ? start + AGENTS_SECTION_HEADER.length + nextExternalHeading.index
+      : content.length,
+  }
 }
 
-const hasPackageSection = (content) => content.includes(AGENTS_SECTION_HEADER)
+const hasPackageSection = (content) => {
+  return Boolean(findMarkedSectionRange(content) || findLegacySectionRange(content))
+}
 
 const appendSection = (content, section) => {
   const trimmed = content.replace(/\s+$/u, '')
 
   if (!trimmed.length) {
-    return `${section}${DEFAULT_NEWLINE}`
+    return `${section.trimEnd()}${DEFAULT_NEWLINE}`
+  }
+
+  return `${trimmed}${DEFAULT_NEWLINE}${DEFAULT_NEWLINE}${section.trimEnd()}${DEFAULT_NEWLINE}`
+}
+
+const replaceRange = (content, range, section) => {
+  const before = content.slice(0, range.start).replace(/\s+$/u, '')
+  const after = content.slice(range.end).replace(/^\s+/u, '')
+  const parts = []
+
+  if (before) {
+    parts.push(before)
   }
 
-  return `${trimmed}${DEFAULT_NEWLINE}${DEFAULT_NEWLINE}${section}${DEFAULT_NEWLINE}`
+  parts.push(section.trimEnd())
+
+  if (after) {
+    parts.push(after)
+  }
+
+  return `${parts.join(`${DEFAULT_NEWLINE}${DEFAULT_NEWLINE}`)}${DEFAULT_NEWLINE}`
 }
 
 const replaceSection = (content, section) => {
-  const escapedHeader = AGENTS_SECTION_HEADER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  const sectionPattern = new RegExp(`${escapedHeader}[\\s\\S]*?(?=\\n##\\s|$)`, 'u')
+  const markedRange = findMarkedSectionRange(content)
+
+  if (markedRange) {
+    return replaceRange(content, markedRange, section)
+  }
+
+  const legacyRange = findLegacySectionRange(content)
 
-  if (!sectionPattern.test(content)) {
-    return appendSection(content, section)
+  if (legacyRange) {
+    return replaceRange(content, legacyRange, section)
   }
 
-  return content
-    .replace(sectionPattern, section.trimEnd())
-    .replace(/\s+$/u, '') + DEFAULT_NEWLINE
+  return appendSection(content, section)
 }
 
 const initAgents = (target, force) => {
@@ -158,10 +342,11 @@ const initAgents = (target, force) => {
   }
 
   const agentsPath = path.join(target, 'AGENTS.md')
-  const section = createAgentsSection()
+  const packageDocsPath = createPackageDocsPath(target)
+  const section = createAgentsSection(packageDocsPath)
 
   if (!fs.existsSync(agentsPath)) {
-    fs.writeFileSync(agentsPath, createAgentsTemplate(), 'utf8')
+    fs.writeFileSync(agentsPath, createAgentsTemplate(packageDocsPath), 'utf8')
 
     console.log(`AGENTS.md was created at ${agentsPath}`)
     console.log('Next step: review it and adjust project-specific rules if needed.')

package/bin/postinstall.mjs

@@ -26,8 +26,9 @@ 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`)
+console.log(`[${PACKAGE_NAME}] AI docs are available in node_modules/${PACKAGE_NAME}/README.md, AGENTS.md, and docs`)
+console.log(`[${PACKAGE_NAME}] Start with README.md, AGENTS.md, docs/AI.md, docs/COMPONENTS.md, and docs/PROFILES.md`)
+console.log(`[${PACKAGE_NAME}] Component profiles live in docs/profiles/components, page profiles live in docs/profiles/pages`)
 
 if (!hasAgentsFile) {
   console.log(`[${PACKAGE_NAME}] To scaffold AGENTS.md for this project, run:`)